VS Code의 Copilot에서 .github/prompts/에 위치한 프롬프트 파일을 /로 호출하여 사용하고 계시지는 않습니까? 편리한 기능이지만, VS Code 공식 문서에서는 프롬프트 파일에서 에이전트 스킬(Agent Skills)로의 마이그레이션을 권장하고 있습니다.
본 기사에서는 프롬프트 파일과 스킬의 차이점, VS Code에 준비된 변환 기능 사용법, 그리고 변환 후 재검토할 사항들을 소개합니다. 예시로는 제가 공개한 doc-to-markdown 프롬프트 파일을 사용하겠습니다.
VS Code와 에이전트 관련 기능은 업데이트가 매우 빠른 분야입니다. 본 기사는 2026년 10월 시점의 공식 문서를 기반으로 작성되었습니다. 화면 항목명 등은 변경될 수 있으므로, 실제로 작업할 때는 공식 문서를 확인해 주십시오.
VS Code 공식 문서에는 프롬프트 파일에 대해 다음과 같이 명시되어 있습니다.
Prompt files are deprecated for Agent Host sessions and aren't loaded by Agent Host. They continue to work with the Local agent for now, but the Local agent will be removed in a future release.
요약하자면, 다음 내용과 같습니다.
Agent Host 세션에서는 프롬프트 파일이 비권장(deprecated)이며 로드되지 않음 - 현재는 Local agent에서 작동하지만, Local agent는 향후 릴리스에서 제거될 예정입니다.
- 마이그레이션 대상은 에이전트 스킬(Agent Skills)입니다.
즉, 당장 작동하지 않는 것은 아닙니다. 다만, 앞으로 새로 만들 때는 스킬로 만들고, 기존에 있는 것도 계획적으로 옮겨가는 것이 안전합니다.
| 프롬프트 파일 | 스킬 (Skill) |
|---|
| 위치 (워크스페이스) | .github/prompts/〇〇.prompt.md |
| 호출 방법 | / + 이름 |
| 형태 | 1개 파일 |
| 필수 항목 | 없음 |
| 사용처 | 주로 VS Code |
가장 큰 차이점은 AI가 스스로 읽을 수 있다는 점입니다. 프롬프트 파일은 사람이 /로 호출하지 않는 한 사용되지 않습니다. 스킬은 description을 보고 '이 요청과 관련이 있다'고 AI가 판단하면 자동으로 내용을 로드합니다.
또 다른 차이점은 폴더 단위로 관리할 수 있다는 것입니다. 절차서와 함께 템플릿이나 보조 스크립트를 같은 폴더에 배치할 수 있습니다.
하네스(Harness) 기사에서 Skills를 '선반에 나열된 업무 매뉴얼'에 비유했습니다. 프롬프트 파일이 '사람이 매번 건네주는 지시서'라면, 스킬은 'AI가 필요할 때 스스로 선반에서 꺼내는 매뉴얼'입니다.
스킬은 많이 준비해도 AI의 부담이 적도록 설계되어 있습니다. 로드 과정은 3단계로 이루어집니다.
- 찾기 (Finding): 먼저
name과 description만 읽고 관련성이 있는지 판단합니다.
- 절차 읽기 (Reading Procedure): 관련성이 있다면,
SKILL.md의 본문을 로드합니다.
- 추가 파일 읽기 (Reading Additional Files): 본문에서 참조된 파일만 필요할 때 읽습니다.
처음에 이름과 설명만 읽기 때문에, 스킬이 늘어나도 매번 대화의 부하가 커지지 않습니다.
VS Code에는 프롬프트 파일을 스킬로 변환하는 기능이 있습니다. 공식 문서 절차는 다음과 같습니다.
- 채팅 뷰에서 스킬을 사용할 Agent Host를 선택합니다.
- 톱니바퀴 아이콘(Configure Chat)에서 Agent Customizations 에디터를 엽니다.
- Overview 탭의 'Migrate Prompt Files'에서 'Convert to Skills...'를 선택합니다.
- 변환할 프롬프트 파일을 선택합니다.
- 'Convert to Skills' 버튼을 누릅니다.
- 확인 다이얼로그에서 원본 프롬프트 파일을 삭제할지 여부를 선택합니다.
처음에는 기존 프롬프트 파일을 삭제하지 않고 변환하는 것을 권장합니다. 변환된 결과와 비교해 보고 문제가 없다면 삭제하세요. Git으로 관리하고 있다면, 삭제해도 되돌릴 수 있습니다.
변환 기능을 사용하면 파일의 형태는 갖추어집니다. 다만, 프롬프트 파일과 스킬은 작성 전제가 다르므로, 내용은 반드시 검토해야 합니다. 여기서는 doc-to-markdown 방식의 프롬프트 파일 /doc2md-investigate-loss (변환 과정에서 내용이 누락되었을 때 원인을 조사하는 기능)를 예로 들어 설명하겠습니다. 원래 파일은 다음과 같습니다(발췌).
---
description: 변환 로스(loss.*의 경고)나 '내용이 부족하다'는 원인을 조사하고, 대처법을 제안한다
agent: agent
...
스킬의 description은 AI가 '이 스킬을 사용해야 하는지'를 판단하는 근거 자료입니다. 공식 문서에서도 'what the skill does and when to use it(무엇을 하는지, 언제 사용하는지)'를 작성하도록 설명하고 있습니다.
프롬프트 파일의 description은 사람이 메뉴에서 볼 수 있는 짧은 설명이었습니다. 하지만 스킬에서는 AI가 판단할 수 있도록 사용 시점까지 작성해야 합니다.
description: >-
doc2md로 Office / PDF를 Markdown으로 변환했을 때, 내용이 누락되지 않았는지 조사한다.
변환 리포트에 loss.* 경고가 발생했거나 '변환 결과에 내용이 부족하다'는 메시지가 나왔을 때 사용한다.
'loss.* 경고가 발생했을 때'처럼 AI가 인지할 수 있는 계기를 작성해 두는 것이 요령입니다.
프롬프트 파일에서는 ${input:path:대상 파일의 경로}와 같은 변수를 사용하여, 호출 시 값을 받을 수 있었습니다. 스킬 설명에는 이 변수의 메커니즘이 나와 있지 않습니다. 스킬을 /로 호출할 때는 이름 뒤에 이어 붙인 문장이 추가적인 지시사항으로 전달됩니다.
/doc2md-investigate-loss samples/expense-flow.pptx
따라서 본문은 '호출 시 지정된 파일'을 전제로 작성하는 것이 좋습니다. 만약 지정이 없을 때 어떻게 할지에 대해서도 적어두면 친절합니다.
대상 파일은 호출할 때 이용자가 지정한 경로입니다.
지정이 없다면, 어떤 파일을 조사할지 이용자에게 질문해 주세요(추측으로 선택하지 마세요).
AI가 자동으로 읽어 들인 경우라면, 대화 흐름 속에서 대상 파일이 결정됩니다. 두 가지 사용 방식 모두 작동하도록 작성하는 것이 좋습니다.
프롬프트 파일에서는 frontmatter의 agent (ask / edit / agent 등)나 tools로 실행 방식을 지정할 수 있었습니다. 공식 문서 스킬 항목 목록에는 이들이 나와 있지 않습니다.
만약 커맨드 실행이 필요한 절차라면, 에이전트(Agent)로서 작동하는 것이 전제가 됩니다. 변환 후, 실제로 /로 호출하여 커맨드를 실행할 수 있는지 확인해 보세요.
스킬에는 호출 방식을 결정하는 두 가지 항목이 있습니다.
| 항목 | 의미 |
|---|
user-invocable | / 메뉴에 노출할지 |
disable-model-invocation | AI가 자동으로 읽어 들이는 것을 막을지 |
사용 기준은 다음과 같습니다.
- 조사나 변환 등, AI에게 자동으로 사용되기를 바라는 경우 → 기본값 유지 -
파일 일괄 치환 등, 사람이 명시적으로 호출할 때만 작동시키고 싶은 경우 → disable-model-invocation: true
되돌릴 수 없는 작업을 하는 스킬은 AI가 임의로 읽어 들이지 않도록 설정해 두는 것이 안전합니다.
네 가지를 반영하면 다음과 같습니다(.github/skills/doc2md-investigate-loss/SKILL.md).
---
name: doc2md-investigate-loss
description: >-
...
절차 본문은 원래 프롬프트 파일과 거의 동일합니다. 바뀐 부분은 frontmatter와 '대상을 어떻게 받을지' 부분뿐입니다.
프롬프트 파일이 많은 경우라면, 다음 순서로 옮기는 것이 안전합니다.
프로프트 파일을 스킬로 이전하는 단계별 가이드
- 목록을 만듭니다.
- 리포지토리에 있는 프로프트 파일들을 모두 파악합니다.
- 자주 사용하는 것 중 하나를 선택하여 변환 기능을 사용해 옮깁니다. 원본 파일은 남겨둡니다.
- 검토합니다.
- 위에서 언급된 네 가지 항목(description, 변수 (variables), 에이전트 및 도구 (agent and tools), 호출 방법)을 확인합니다.
- 테스트합니다.
/로 호출하여 작동하는지, 또는 관련 요청을 했을 때 AI가 자동으로 로드하는지 확인합니다.
- 나머지를 옮깁니다.
- 첫 번째 항목에서 얻은 노하우를 활용하여 나머지 파일들도 변환합니다.
- 원본 프로프트 파일을 삭제합니다. README 등에
/ 사용법이 적혀 있다면, 그 부분도 수정해야 합니다.
마지막 단계는 종종 잊기 쉽습니다. README에 "Copilot Chat에서 /〇〇이라고 입력"과 같이 작성되어 있다면, 스킬의 이름 및 호출 방식에 맞춰 업데이트해야 합니다.
description을 간결하게 유지하지 마세요.
프로프트 파일의 짧은 설명만으로는 AI가 해당 스킬을 사용해야 할 상황을 판단할 수 없습니다. '무엇을 하는지'뿐만 아니라 '언제 사용하는지'를 함께 작성해야 합니다.
${input:...}와 같은 변수 플레이스홀더가 그대로 남아있게 됩니다.
변수가 그대로 남아 있으면 AI에게는 단순한 문자열로 보일 수 있습니다. 변환 후에는 ${를 검색하여 혹시 남아있는 부분이 없는지 확인하는 것이 좋습니다.
위험한 작업도 자동으로 로드되도록 설정된 상태를 유지하지 마세요.
파일을 수정하는 스킬이 AI의 판단에 의해 임의로 사용되는 것은 문제가 될 수 있습니다. 사람이 호출했을 때만 작동해야 하는 기능은 disable-model-invocation: true로 설정해 두는 것이 좋습니다.
모두 한 번에 옮기면, 어떤 것이 작동하지 않는지 알기 어렵습니다.
먼저 하나를 옮겨 테스트하고 노하우를 얻은 후에 나머지 파일들을 확장하는 방식으로 진행하세요.
프로프트 파일은 스킬로 이전하는 것이 권장됩니다. 변환 기능을 사용하면 형태는 금방 갖출 수 있지만, 내용 검토까지 마쳐야 완성입니다.
- description에 '언제 사용하는지'를 작성합니다.
${input:...}를 지정된 내용을 받을 수 있는 방식으로 수정합니다.- 위험한 작업은 사람이 호출했을 때만 작동하도록 설정합니다.
스킬로 만들어 두면 VS Code 외의 에이전트에서도 사용할 수 있게 되며, AI가 필요할 때 스스로 로드해 줍니다. 매번 사람이 전달하던 지시서를 AI가 스스로 꺼내 쓸 수 있는 매뉴얼로 바꿔나가야 합니다.
- Use prompt files in VS Code
- Use Agent Skills in VS Code
- Agent customization overview (Migrate prompt files to skills)
이 글은 Zenn에도 게시되었습니다.
