SKILL.md를 '사양서로 작성'하기보다 'Claude에게 작성하게 하는 것'이 더 올바른 이유

본 기사는 playpark Blog에서 전재된 내용입니다.

• '사양서를 읽고 작성하는 것'보다 'Claude에게 작성하게 한 후 조정하는 것'이 합리적인 이유
• description 필드가 구동 정밀도를 좌우하는 메커니즘과 판단 기준
• 스킬이 원하는 대로 작동하지 않을 때, 무엇을 수정해야 하는가

Claude Code의 Skills를 사용해 보려고 할 때, 많은 사람이 가장 먼저 마주치는 의문은 'SKILL.md는 어떻게 작성해야 하는가'입니다. 공식 문서를 읽으면 frontmatter 필드 목록이 나오지만, allowed-tools나 model, 같은 항목들의 활용처는 실제로 만들어보지 않으면 감이 오지 않습니다.

'사양을 전부 이해한 후에 쓰자'라고 생각하면 그대로 손이 멈춥니다.

SKILL.md를 작성하는 방법으로 실질적으로 두 가지 접근 방식이 있습니다.

접근 방식	진행 과정	비용
사양서를 먼저 읽기	frontmatter의 모든 필드를 파악한 후 작성	학습 비용 높음 / 실제 동작과 괴리하기 쉬움
Claude에게 작성하게 하기 (채택)	작업을 한 번 거친 후 'skill화 해달라'고 요청	학습 비용 낮음 / 실제 동작 기반으로 생성됨

사양서를 먼저 읽는 접근 방식은 언뜻 정확해 보이지만, '어떤 필드를 어떻게 조합해야 기대한 대로 작동하는지'는 실제로 사용해보지 않으면 모르는 부분이 많습니다. Claude에게 작성하게 할 경우, 생성된 SKILL.md는 최근 대화의 문맥을 반영하기 때문에 실제 동작에 맞는 기술이 되기 쉽습니다.

실제 운용 관점에서 두 가지 이유가 컸습니다.

1. frontmatter의 최소 구성은 name + description의 2개 필드로 충분하다

Claude가 출력하는 SKILL.md는 대략 이런 형태입니다.

---
name: blog-fact-check
description: 'MDX 기사 내 통계 데이터・버전 정보・요금을 추출하여 공식 소스와 대조한다. 사용자가 

에피크(Epic)로 분할하여 컨텍스트 소비를 줄이는 접근 방식 - 프로젝트 고유값을 `skill-config.json`에 외부에 저장하는 포터블 설계

**playpark LLC** - 업무 자동화・AI 활용・웹 개발