Skill.md의 description을 잘못 작성하면 스킬이 작동하지 않는 이유

「스킬을 만들었는데 사용되지 않는다」는 경험

Codex나 Claude Code로 스킬을 만들기 시작하면, 처음에는 이런 상황에 자주 부딪힌다.

SKILL.md 파일을 작성하여 디렉토리에 배치했는데, '배포해 줘'라고 지시했음에도 불구하고 왜인지 스킬이 작동하지 않는다.

• description을 작성했지만, 에이전트가 스킬을 인식하지 못하는 것처럼 보인다.

원인을 조사해보면 거의 매번 description의 작성 방식에 도달한다.

이 글에서는 description이 왜 스킬 작동 여부를 좌우하는지, 그리고 어떻게 작성해야 확실하게 작동하는지를 판단 이유와 함께 설명한다.

description은 Level 1 메타데이터로서 항상 컨텍스트에 포함된다

Skill.md의 기본 구조는 간단하다.

---
name: my-awesome-skill
description: |
...

프론트매터(frontmatter)는 name과 description 두 필드가 필수다. Claude Code Skills에서는 allowed-tools도 사용할 수 있지만, 기본적으로 이 두 가지가 핵심이다.

본문(Markdown 본문)은 지연 로드된다. 에이전트는 모든 스킬의 본문을 상시 컨텍스트에 유지하는 것이 아니라, description만을 Level 1 메타데이터로 상시 참조한다. 사용자의 지시에 맞는 스킬을 선택할 때, 에이전트는 오직 description만 보고 판단하고 있다.

따라서 description이 모호하면, 본문에 아무리 상세한 절차를 작성해도 스킬 자체가 선택되지 않는다.

왜 이렇게 작성해야 하는가

description을 짧게 하고 본문에 자세히 쓰면 된다고 생각하기 쉽지만, 그것은 잘못이다. 에이전트의 동작 모델로 볼 때, description은 '스킬 검색 인덱스'에 해당한다. 검색에 걸리지 않으면, 내용이 아무리 좋아도 사용되지 않는다.

작동하는 description과 작동하지 않는 description의 차이

패턴	문제점
`description:

Claude Code 고유의 기능으로 allowed-tools가 있다.

---
name: safe-deploy
description: |
...

이것은 보안 설계에 관한 이야기다. '이 스킬은 Read와 Bash만 사용할 수 있다'고 명시함으로써, 스킬이 의도하지 않은 파일 변경을 할 위험을 제거할 수 있다. Codex Skills에는 이 기능이 없기 때문에, 크로스 플랫폼에서 사용하고 싶은 스킬에서는 allowed-tools를 생략한다.

내가 이렇게 작성하는 방식

description의 영어 vs 일본어 문제가 자주 화제가 된다. description은 영어로 작성해야 한다는 것은 변함이 없다. 에이전트의 매칭 정확도는 영어가 가장 안정적이다. 다만 본문(Markdown 본문)은 일본어로 해도 괜찮다.

본문의 길이에 대해서는, 500줄을 초과하면 references/에 분할한다는 운영 방식을 취하고 있다.

my-skill/
├── SKILL.md ← 500줄 이내
├── scripts/
...

본문이 길어진다는 것은, 스킬에 여러 책임이 혼재되어 있다는 신호이기도 하다. '1스킬 1책임'을 의식하면, 자연스럽게 500줄 이내로 수렴하는 경우가 많다.

Codex에서도 Claude Code에서도 작동하는 스킬을 작성하려면, allowed-tools를 생략한 공통 구조만 사용한다. 플랫폼 고유의 확장이 필요하다면 별도의 디렉터리에서 관리한다는 방침이 결과적으로 심플했다.

원문 기사

이 기사는 Skill.md 작성 가이드 — Codex Skills와 Claude Code Skills의 차이점 및 설계 패턴의 핵심 부분을 재구성한 것입니다. 원문에서는 더 나아가 다음과 같은 내용을 다루고 있습니다:

• 툴을 넘나들며 재사용할 수 있는 3가지 스킬 설계 패턴 (호환성 중시・플랫폼별 확장・참조 파일 공유)
• 커밋 메시지 생성 스킬의 완전 구현 예시 (Conventional Commits 대응)
• Codex 공식 스킬 카탈로그 openai/skills 활용 방법과 경량 모델 실행에 대한 고찰

이 기사는 playpark Blog에서 전재된 것입니다.

Discussion