Copilot 프롬프트 파일을 스킬로 옮기기: 변환 기능 사용법과 재작성 팁

VS Code의 Copilot에서 .github/prompts/에 놓인 프롬프트 파일을 /로 호출하여 사용하고 계시지는 않나요? 편리한 기능이지만, VS Code 공식 문서에서는 프롬프트 파일에서 에이전트 스킬(Agent Skills)로의 전환을 권장하고 있습니다.

본문에서는 프롬프트 파일과 스킬의 차이점, VS Code에 마련된 변환 기능 사용법, 그리고 변환 후 재검토할 부분을 소개합니다. 예시로는 제가 공개한 doc-to-markdown 프롬프트 파일을 사용하겠습니다.

무슨 일이 일어나고 있는가

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는 향후 릴리스에서 제거될 예정입니다.

• 전환할 곳은 에이전트 스킬입니다.

즉, 당장 작동하지 않게 되는 것은 아닙니다. 다만, 앞으로 새로 만들 것이라면 스킬로 만들고, 기존에 있는 것도 계획적으로 옮겨가는 것이 안전합니다.

프롬프트 파일과 스킬의 차이점

| 프롬프트 파일 | 스킬 | |
|---|---| |
| 위치 (워크스페이스) | .github/prompts/〇〇.prompt.md | .github/skills/〇〇/SKILL.md |
| 호출 방법 | / + 이름 | / + 이름(사람이 호출), 또는 관련 요청 시 AI가 자동으로 로드함 |
| 형태 | 1개 파일 | 폴더 (템플릿이나 스크립트를 함께 배치 가능) |
| 필수 항목 | 없음 | name과 description |
| 사용처 | 주로 VS Code | VS Code, GitHub Copilot CLI, Copilot coding agent 등 |

가장 큰 차이점은 AI가 스스로 로드할 수 있다는 것입니다. 프롬프트 파일은 사람이 /로 호출하지 않는 한 사용되지 않습니다. 스킬은 description을 보고

처음에는 원래의 프롬프트 파일을 삭제하지 않고 변환하는 것이 좋습니다. 변환 결과를 비교해 보고 문제가 없으면 삭제하세요. Git으로 관리하고 있다면, 지워도 되돌릴 수 있습니다.

변환 후 다시 살펴보고 싶은 4가지 사항

변환 기능으로 파일의 형태는 갖춰집니다. 하지만 프롬프트 파일과 스킬은 작성하는 전제가 다르므로, 내용은 반드시 재검토해야 합니다. 여기서는 doc-to-markdown 프롬프트 파일 /doc2md-investigate-loss (변환 과정에서 내용이 누락된 원인을 조사)를 예로 들어보겠습니다. 원래 파일은 다음과 같습니다(발췌).

---
description: 변환 손실(loss.* 경고)이나 '내용이 부족함'의 원인을 조사하고, 대처법을 제안한다
agent: agent
...

1. description에 '언제 사용하는지'를 작성하기

스킬의 description은 AI가 '이 스킬을 사용해야 하는지'를 판단하는 자료입니다. 공식 문서에서도 'what the skill does and when to use it (무엇을 하는지, 언제 사용할지)'를 작성하라고 설명하고 있습니다.

프롬프트 파일의 description은 사람이 메뉴에서 보기 위한 짧은 설명이었습니다. 스킬에서는 AI가 판단할 수 있도록 사용하는 상황까지 적습니다.

description: >-
doc2md로 Office / PDF를 Markdown으로 변환했을 때, 내용이 누락되지 않았는지 조사한다.
변환 리포트에 loss.* 경고가 발생했거나, 또는 '변환 결과에 내용이 부족하다'는 말을 들었을 때 사용한다.

'loss.* 경고가 발생했을 때'처럼 AI가 인지할 수 있는 계기를 작성해 두는 것이 요령입니다.

${input:...} 변수 다시 쓰기

2. 프롬프트 파일에서는 ${input:path:대상 파일의 경로}와 같은 변수로, 호출할 때 값을 받을 수 있었습니다. 스킬 설명에는 이 변수의 메커니즘이 나와 있지 않습니다. 스킬을 /로 호출할 때는 이름 뒤에 이어서 작성한 문장이 추가적인 지시사항으로 전달됩니다.

/doc2md-investigate-loss samples/expense-flow.pptx

여기서 본문은 '호출했을 때 지정된 파일'을 전제로 한 방식으로 수정합니다. 지정이 없을 때 어떻게 할지도 적어두면 친절합니다.

대상 파일은, 호출했을 때 이용자가 지정한 경로입니다.
지정이 없다면, 어떤 파일을 조사할지 이용자에게 질문해 주세요(추측으로 선택하지 마세요).

AI가 자동으로 로드된 경우에는, 대화의 흐름 속에서 대상 파일이 결정됩니다. 어느 쪽 사용 방식에서도 작동하도록 작성하는 것이 좋습니다.

agent나 tools 지정 확인하기

3. 프롬프트 파일에서는 frontmatter의 agent (ask / edit / agent 등)나 tools로 실행 방법을 지정할 수 있었습니다. 공식 문서의 스킬 항목 목록에는 이것들이 나와 있지 않습니다.

커맨드 실행이 필요한 절차라면, 에이전트로 작동하는 것이 전제가 됩니다. 변환 후에 실제로 /로 호출하여 커맨드를 실행할 수 있는지 확인해 보세요.

4. 호출 방식을 정하기

스킬에는 호출 방식을 결정하는 두 가지 항목이 있습니다.

• 조사나 변환 등, AI에게 자동으로 사용했으면 하는 것 → 기본값 유지 -
  파일 일괄 치환 등, 사람이 명시적으로 호출했을 때만 작동하고 싶은 것 → disable-model-invocation: true

되돌릴 수 없는 작업을 하는 스킬은 AI가 멋대로 로드되지 않도록 해 두는 것이 안심입니다.

수정된 예시

4가지를 반영하면 다음과 같습니다(.github/skills/doc2md-investigate-loss/SKILL.md).

---
name: doc2md-investigate-loss
description: >-
...

본문 진행 과정은 원래의 프롬프트 파일과 거의 같습니다. 달라진 부분은 frontmatter와 '대상을 어떻게 받을지' 부분뿐입니다.

옮기는 순서

프롬프트 파일이 많이 있는 경우, 다음 순서로 옮기는 것이 안전합니다.

• 목록을 만든다. 리포지토리에 있는 프롬프트 파일을 파악한다 -
• 자주 사용하는 것을 하나 골라 변환 기능을 사용해 옮긴다. 원래 파일은 남겨둔다 -
• 검토한다. 위의 4가지(description, 변수, agent와 tools, 호출 방법)를 확인한다 -
• 시도해 본다. /로 불러서 작동하는지, 관련 요청을 했을 때 AI가 자동으로 읽어들이는지 확인한다 -
• 나머지를 옮긴다. 첫 번째 단계에서 알게 된 요령을 사용해 나머지 파일도 변환한다 -
• 원래 프롬프트 파일을 지운다. README 등에 /의 사용법을 적었다면, 그 부분도 수정합니다.

마지막 단계는 잊기 쉽습니다. README에 'Copilot Chat에서 /〇〇라고 입력'이라고 적혀 있다면, 스킬의 이름과 호출 방식에 맞춰 업데이트합시다.

흔한 실수

description을 짧게 유지하는 것

프롬프트 파일의 설명이 짧으면 AI가 스킬을 사용할 상황을 판단할 수 없습니다. '무엇을 하는지'에 더해 '언제 사용하는지'를 작성합시다.

${input:...}

이 그대로 남아 있는 경우

변수가 그대로 남아 있으면, AI에게는 단순한 문자열로 보입니다. 변환 후에 ${으로 검색하여 남아 있는지 확인합시다.

위험한 작업도 자동으로 읽어들여지도록 설정 상태를 유지하는 것

파일을 수정하는 스킬이 AI의 판단에 의해 멋대로 사용되면 곤란합니다. 사람이 호출할 때만 작동하고 싶은 것은 disable-model-invocation: true로 설정해둡니다.

한 번에 전부 옮겨서 어떤 것이 작동하지 않는지 알 수 없는 것

우선 하나를 옮겨 테스트해보고, 요령을 터득한 후에 나머지 파일에 적용합시다.

요약

프롬프트 파일은 스킬로의 이관이 권장됩니다. 변환 기능을 사용하면 형태는 금방 갖출 수 있지만, 내용 검토까지 해야 완성입니다.

• description에 '언제 사용하는지'를 작성한다
• ${input:...}을 지정된 내용을 받는 방식으로 수정한다 - 위험한 작업은 사람이 호출할 때만 작동하도록 한다

스킬로 만들어 두면 VS Code 외의 에이전트에서도 사용할 수 있게 되고, AI가 필요할 때 스스로 읽어들여 줍니다. 사람이 매번 전달하던 지시서를 AI가 스스로 꺼낼 수 있는 매뉴얼로 바꿔 나갑시다.

참고

Discussion