이 기사에서 알 수 있는 것

Agent Skill (SKILL.md)를 만들려고 할 때, 애초에 어떻게 써야 할지 모르겠거나, 써봐도 생각한 대로 움직이지 않는 경우가 자주 발생합니다.

사용되기를 원하는 상황에서 호출되지 않거나, 반대로 관계없는 상황에서 멋대로 작동하기도 합니다.

이 기사에서는 먼저 공식 가이드가 제시하는 기본을 정리합니다.

그 후에 실제로 여러 개의 스킬을 만들어보며 "이렇게 쓰는 것이 더 잘 작동한다"라고 느낀 점을 경험칙으로서 기술하겠습니다.

전반부가 토대, 후반부가 실전이라는 구성입니다.

전반부: 공식 가이드가 제시하는 기본

먼저 Anthropic의 Skill authoring best practices가 제시하는 기본을 확인합니다.

이 부분은 반드시 지켜야 합니다. 이하 "무엇을 하는가", "왜 그렇게 하는가", "공식 가이드의 기술(원문)" 순으로 정리합니다.

name과 description 두 가지만 사용하기

1. frontmatter는 왜: 기동 시 시스템 프롬프트(system prompt)로 읽어들이는 것이 이 두 가지뿐이기 때문입니다. 다른 필드를 추가하더라도 스킬이 선택될지 여부를 판단하는 데에는 사용되지 않습니다.

공식 가이드의 기술:

The SKILL.md frontmatter requires two fields:

name:

• Maximum 64 characters
• Must contain only lowercase letters, numbers, and hyphens
• Cannot contain XML tags
• Cannot contain reserved words: "anthropic", "claude"

description:

• Must be non-empty
• Maximum 1,024 characters
• Cannot contain XML tags
• Should describe what the Skill does and when to use it

description에 "무엇을 하는가"와 "언제 사용하는가"를 모두 작성하기

2. 왜: description은 수많은 스킬 중에서 어떤 것을 사용할지 판단하기 위한 정보이기 때문입니다. 기능에 대한 설명만으로는 사용해야 할 상황을 판단할 수 없습니다.

공식 가이드의 기술:

The description field enables Skill discovery and should include both what the Skill does and when to use it.

Be specific and include key terms. Include both what the Skill does and specific triggers/contexts for when to use it. Each Skill has exactly one description field. The description is critical for skill selection: Claude uses it to choose the right Skill from potentially 100+ available Skills.

description은 3인칭으로 작성하기

3. 왜: description은 시스템 프롬프트에 삽입되기 때문에, 시점이 섞이면 판단이 흔들릴 수 있기 때문입니다.

공식 가이드의 기술:

Always write in third person. The description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems.

Good: "Processes Excel files and generates reports"
Avoid: "I can help you process Excel files"
Avoid: "You can use this to process Excel files"

name은 동명사 또는 명사구로 통일하기

4. 왜: 이름을 보는 것만으로도 어떤 스킬인지 알 수 있게 하기 위해서입니다. 명명 규칙이 들쑥날쑥하면 스킬이 늘어났을 때 관리가 불가능해집니다.

공식 가이드의 기술:

스킬을 더 쉽게 참조하고 논의할 수 있도록 일관된 명명 패턴을 사용하세요. 스킬이 제공하는 활동이나 능력을 명확하게 설명할 수 있도록 스킬 이름에 동명사 형태(verb + -ing)를 사용하는 것을 고려하십시오.

피해야 할 사례:

• 모호한 이름:
  helper
  , utils
  , tools

• 지나치게 일반적인 이름:
  documents
  , data
  , files

• 예약어(Reserved words):
  anthropic-helper
  , claude-tools

• 스킬 컬렉션 내의 일관되지 않은 패턴

5. SKILL.md의 본문은 500행 미만으로 유지하기

이유: 컨텍스트 윈도우 (Context Window)는 대화 기록이나 다른 스킬과 공유되는 자원이기 때문입니다. 로드되는 순간부터 모든 토큰이 다른 정보와 경합하게 됩니다.

공식 가이드의 기술:

최적의 성능을 위해 SKILL.md 본문을 500행 미만으로 유지하십시오. 콘텐츠가 이를 초과하는 경우, 앞서 설명한 점진적 공개 (Progressive Disclosure) 패턴을 사용하여 별도의 파일로 분리하십시오.

6. 상세 내용은 별도 파일로 분리하여 필요할 때만 읽게 하기

이유: 파일은 파일 시스템 상에 존재하며, 실제로 읽히기 전까지는 토큰을 소비하지 않기 때문입니다. 한꺼번에 가지고 있더라도 사용하지 않는다면 비용이 발생하지 않습니다.

공식 가이드의 기술:

SKILL.md는 온보딩 가이드의 목차처럼, Claude가 필요에 따라 상세 자료를 참조할 수 있도록 안내하는 개요 역할을 합니다.

대용량 파일에 대한 컨텍스트 페널티(Context Penalty) 없음: 참조 파일, 데이터 또는 문서는 실제로 읽히기 전까지 컨텍스트 토큰을 소비하지 않습니다.

7. 참조 파일은 SKILL.md로부터 1단계 계층까지만 구성하기

이유: 참조된 대상이 또 다른 대상을 참조하게 되면, 중간까지만 읽히는 경우가 발생할 수 있기 때문입니다.

공식 가이드의 기술:

Claude는 다른 참조 파일로부터 파일이 참조될 때 파일을 부분적으로 읽을 수 있습니다. 중첩된 참조(Nested references)를 만날 경우, Claude는 전체 파일을 읽는 대신 head -100과 같은 명령어를 사용하여 내용을 미리 보기 할 수 있으며, 이는 정보의 불완전함으로 이어질 수 있습니다.

참조는 SKILL.md로부터 1단계 깊이(one level deep)로 유지하십시오. Claude가 필요할 때 전체 파일을 읽을 수 있도록 모든 참조 파일은 SKILL.md에서 직접 연결되어야 합니다.

8. 결정론적인 처리는 스크립트로 작성하여 동봉하기

이유: 매번 코드를 생성하게 하면 내용이 일관되지 않을 뿐만 아니라, 토큰과 시간도 소비하기 때문입니다.

공식 가이드의 기술:

결정론적인 동작(Deterministic operations)에는 스크립트를 선호하십시오: Claude에게 검증 코드를 생성하도록 요청하는 대신 validate_form.py를 작성하십시오.

유틸리티 스크립트의 이점:

• 생성된 코드보다 더 신뢰할 수 있음
• 토큰 절약 (컨텍스트에 코드를 포함할 필요가 없음)
• 시간 절약 (코드 생성 과정이 필요 없음)
• 사용 시 일관성 보장

9. 태스크의 취약성(Fragility)에 따라 자유도를 조절하기

이유: 정답이 여러 개인 작업과, 절차를 하나라도 틀리면 실패하는 작업은 필요한 지시의 세밀함이 다르기 때문입니다.

공식 가이드의 기술 내용:

태스크의 취약성(Fragility) 및 가변성(Variability)에 맞춰 구체성(Specificity) 수준을 맞추십시오.

높은 자유도(텍text 기반 지시): 다음과 같은 경우에 사용: 여러 접근 방식이 유효할 때 / 결정이 컨텍스트에 따라 달라질 때 / 휴리스틱(Heuristics)이 접근 방식을 안내할 때

중간 자유도(매개변수가 있는 의사코드(Pseudocode) 또는 스크립트): 다음과 같은 경우에 사용: 선호되는 패턴이 존재할 때 / 어느 정도의 변형이 허용될 때 / 설정(Configuration)이 동작에 영향을 미칠 때

낮은 자유도(특정 스크립트, 매개변수가 거의 없거나 없음): 다음과 같은 경우에 사용: 작업이 취약하고 오류가 발생하기 쉬울 때 / 일관성이 매우 중요할 때 / 특정 순서를 반드시 따라야 할 때

여기까지가 공식 가이드의 기본입니다.

후반부: 실제로 만들어보며 알게 된 것

여기서부터는 실제로 스킬을 만들어 작동시켜 본 결과와, 이미 공개되어 있는 완성도 높은 스킬들을 다수 읽고 관찰하며 발견한 공통 패턴을 기술하겠습니다.

공식 가이드는 '좋은 스킬의 형태'를 알려주지만, 실제 대화에서 어떻게 트리거(Trigger)되는가 하는 부분은 직접 만들어 테스트하거나, 잘 작동하는 스킬의 작성 방식을 관찰하지 않으면 알 수 없습니다.

다음은 그 두 가지를 통해 얻은 실전적인 내용입니다. 기존 스킬에서 공통적으로 발견된 작성 방식에 대해서는 그 취지를 명시하였습니다.

각 항목은 「Context(전제) → Practice(이렇게 작성하기) → Anti-pattern(이렇게 작성하지 않기)」 순으로 정리합니다.

SKILL.md 작성법: 분할은 '행 수'가 아니라 '분기'로 판단한다

Context(전제)

공식 가이드의 '500행 미만'은 컨텍스트(Context)를 압박하지 않기 위한 기준으로 적절합니다. 실제로 기준 없이 계속 쓰다 보면 확실히 비대해집니다.

하지만 이를 '행 수가 늘어나면 분할한다'라는 기계적인 규칙으로 운용하면 오히려 다루기 어려워질 수 있습니다.

실제로 효과적이었던 방법은 행 수를 기준으로 삼되, 독립적인 분기(Branch)가 있는지 여부로 판단하는 것이었습니다. 행 수는 어디까지나 '재검토의 계기'일 뿐이며, 분할 여부는 내용의 구조로 결정합니다.

Practice(이렇게 작성하기)

절차가 일직선으로 진행되는 태스크는 행 수가 늘어나더라도 하나의 파일로 합칩니다. 분기가 없는 절차를 억지로 나누면, 본래 하나로 이어지던 흐름이 끊겨 중간 절차를 읽지 않은 채 다음으로 넘어가 버리는 경우가 발생할 수 있습니다.

반대로, '신규 생성'과 '장애 조사'처럼 진입점(Entry point)은 같더라도 수행하는 작업이 완전히 다른 워크플로우(Workflow)로 나뉘는 경우에는 본체가 짧더라도 분할합니다. 이 두 가지를 하나의 파일에 함께 두면, 작성 절차를 읽으면서 조사를 시작하는 식의 혼선이 발생합니다.

판단 기준은 다음과 같습니다. 분할된 스킬들을 살펴보면 대체로 이 기준에 따라 나누어져 있었습니다.

Anti-pattern(이렇게 작성하지 않기)

행 수가 늘어났다는 이유만으로 일직선인 절차를 기계적으로 자르지 않습니다. 다만, 기준을 크게 초과한 상태로 방치하지도 않습니다. 초과했을 때는 '정말로 하나의 흐름인가'를 재검토합니다.

반대로, 명백히 별개의 워크플로우인 것을 아직 짧다는 이유로 하나의 파일에 몰아넣지 않습니다.

진입점 스킬: 처리를 갖지 않는다

Context(전제)

분할하면, 진입점이 되는 SKILL.md는 분류 전용이 됩니다. 이곳은 실제 처리를 작성하는 파일과는 작성 방식이 다릅니다.

Practice (이렇게 작성한다)

서두에 "이 스킬 자체는 처리를 갖지 않는다"라고 선언합니다. 진입점에 절차의 파편이 남아 있으면, 자식 스킬을 읽지 않고 그 파편만으로 처리를 시작해 버리는 경우가 있기 때문입니다.

이 스킬은 처리 내용을 가지지 않습니다.
반드시 아래 표에서 해당되는 자식 스킬을 로드한 후 작업을 시작해 주세요.

분류 조건은 하나의 표로 정리합니다. 이는 기존 스킬들을 읽으면서 공통적으로 발견한 작성 방식인데, 조건을 본문의 여기저기에 분산시키면 업데이트할 때 어긋나기 때문이라고 이해했습니다.

지시는 능동태로 작성합니다. 잘 만들어진 스킬은 "자세한 내용은 여기를", "참조해 주세요"와 같은 수동적인 안내를 거의 사용하지 않고, "./create/SKILL.md를 로드해 주세요"와 같이 동사로 명령하는 형태로 통일되어 있었습니다. 수동적인 안내는 읽기 쉽지 않기 때문이라고 생각됩니다.

자식 스킬을 이름으로 해결(Resolve)할 수 없는 경우의 대체 경로도 적어둡니다. 환경에 따라 해결에 실패할 수 있으며, 그때 자기 방식대로 처리를 진행하면 품질이 무너지기 때문입니다.

자식 스킬을 이름으로 해결할 수 없는 경우에는,
`./troubleshoot/SKILL.md`를 직접 읽어 들여 마지막까지 실행해 주세요.

Anti-pattern (이렇게 작성하지 않는다)

진입점에 "자주 발생하는 케이스는 이렇게 대처한다"와 같은 처리의 파편을 남기지 않습니다.

분류 조건을 본문의 여러 곳에 분산시키지 않습니다.

description을 생략한다

말단 스킬: Context (전제)

진입점에서 지목하여 로드되는 말단 스킬에는 description을 쓰지 않는 편이 잘 작동합니다.

description은 자동 발화(Auto-firing)를 위한 정보이며, 말단 스킬은 애초에 자동 발화시킬 필요가 없기 때문입니다.

Practice (이렇게 작성한다)

진입점 스킬에는 description을 상세히 작성합니다. 이곳이 호출될지 여부를 결정합니다.

말단 스킬에는 무엇을 하는지, 전제, 출력만을 간결하게 적습니다. 트리거 단어의 나열은 불필요합니다.

Anti-pattern (이렇게 작성하지 않는다)

모든 SKILL.md에 동일한 밀도로 트리거 단어를 적지 않습니다. 기동 시 읽어 들여야 하는 메타데이터가 늘어나고, 그만큼 다른 정보와 충돌하게 됩니다.

말단 스킬에 "~할 때 사용한다"라고 적어 진입점과 충돌하게 만들지 않습니다.

description 작성법: "언제 부르지 마라"를 적는다

Context (전제)

공식 가이드에서 말하는 "무엇을 하는가", "언제 사용하는가"는 필요한 정보이지만, 그것만으로는 폭발적인 오작동(暴発)을 막을 수 없습니다. 실제로 문제가 되는 것은 대개 호출하고 싶지 않은 상황이 적혀 있지 않기 때문입니다.

description은 오작동(Mis-firing)과 놓침(Miss)을 없애 나가는 작업 로그를 두는 곳이라고 생각하면 다루기 쉬워집니다.

Practice (이렇게 작성한다)

호출하지 않을 조건을 구체적인 예시와 함께 적습니다. 추상적인 제외 조건은 효과가 약하기 때문에, 실제로 오작동했던 케이스의 문구를 그대로 적습니다.

description: >-
(무엇을 하는지에 대한 설명)...
다음의 경우에는 사용하지 않음: 특정 ID를 지정한 참조(상세 취득 스킬을 사용), 
...

발화 방침에는 그 이유도 덧붙입니다. "헷갈리면 호출한다"라고만 적으면 판단이 흔들리기 때문에, 왜 그쪽을 선택하는지 적습니다.

헷갈릴 경우에는 호출하는 쪽을 선택한다. 호출 비용은 작고, 놓쳤을 때의 비용은 크기 때문이다.

너무 자주 호출하는 것이 해가 되는 스킬이라면, 반대로 "헷갈리면 호출하지 않는다, 이유는 ~"라고 적습니다. 판단 기준 그 자체보다 판단의 근거를 적는 편이 안정적입니다.

멈추는 방법도 동일한 description에 적습니다. 적극적으로 발화시키면 이번에는 "끈질기다"라는 문제가 발생하기 때문입니다.

해당 요구가 한 번 해결된 후에는, 미요구 상태로 재제안하지 않는다.
단, 사용자가 명시적으로 요구한 경우에는 과거의 대화 내용과 관계없이 항상 발화한다.

이때, 중단하는 범위를 대화 단위로 설정하지 않는 것이 중요합니다. 대화 단위로 중단하면, 다른 화제로 넘어갔을 때 다시는 발화하지 않게 됩니다. "같은 요구에 대해서는 중단한다, 다른 요구라면 다시 발화한다"라고 명확히 구분하여 작성합니다.

유사한 기능의 도구가 있는 경우에는 대체인지 병용인지 명시합니다. 이 부분이 모호하면 한쪽만 실행됩니다.

이 스킬은 ○○ 도구의 대체가 아니다. 양쪽을 같은 턴에 실행할 것.
(대상으로 하는 범위가 다르며, 보완 관계에 있기 때문)

Anti-pattern (이렇게 쓰지 마세요)

"~에 도움이 됩니다"라고만 쓰고, 호출하지 않을 조건을 쓰지 않은 채로 두지 마세요.

트리거 단어(Trigger words)를 나열하는 것만으로 끝내지 마세요. 열거는 누락을 방지하는 데는 효과적이지만, 폭주(over-triggering)를 억제하는 데는 별로 효과적이지 않다는 인상을 줍니다.

"항상 사용한다"라고 쓰면서, 중단하는 방법을 쓰지 않은 채로 두지 마세요.

유사한 기능의 스킬: 서로 "내가 아니다"라고 작성하기

Context (전제)

기능이 비슷한 스킬이 여러 개 있으면 서로 차지하려는 경향이 생기기 쉽습니다.

이는 각각의 스킬이 자신의 담당이 아닌 케이스를 작성함으로써 해결할 수 있습니다.

예를 들어 다음 세 가지가 나열된 상황을 가정해 봅니다.

• A: 단발성 파일 처리
• B: 지속적인 파이프라인 구축
• C: 이미 테이블에 있는 데이터에 대한 함수 적용

Practice (이렇게 작성하세요)

A의 description 끝에 "지속적으로 계속 처리하고 싶다면 B를 사용한다"라고 작성합니다.

B에는 "단발성이라면 A, 파일을 동반하지 않고 테이블 위의 데이터만 다룬다면 C에 맡긴다"라고 작성합니다.

상대방의 스킬 이름은 직접 지칭하여 작성합니다. "다른 스킬을 사용해 주세요"라고 하면 어디로 가야 할지 알 수 없어 해결되지 않습니다.

그리고 양방향으로 작성합니다. 한쪽에만 작성하면, 작성되지 않은 쪽이 담당 외의 일을 계속 가로채게 됩니다.

Anti-pattern (이렇게 쓰지 마세요)

"~에도 대응 가능"이라며 방어 범위를 넓게 작성하지 마세요. 옆의 스킬과 충돌합니다.

자신의 특기 분야만 쓰고, 경계를 작성하지 않은 채로 두지 마세요.

참조 파일: "읽어라"가 아니라 "읽기 전에 쓰지 마라"라고 작성하기

Context (전제)

상세한 사양이나 스키마를 외부에 분리하는 것 자체는 공식 가이드와 같지만, 분리한 결과로 읽히지 않은 채 작업이 진행되어 버리는 경우가 있습니다.

"상세 내용은 references/api.md를 참조"라고 써도, 그대로 자기 방식대로 쓰기 시작해 버리는 상태입니다.

Practice (이렇게 작성하세요)

읽는 타이밍을 다음 행동의 전제로 작성합니다.

`references/api.md`를 읽기 전에, 이 API를 사용하는 코드를 작성하지 마세요.

"참조한다"가 아니라 "읽지 않고는 다음 행동을 하지 않는다"라는 형태로 만들면 순서가 지켜집니다.

100행을 초과하는 참조 파일에는 서두에 목차를 붙입니다. 부분적으로 읽히더라도 무엇이 적혀 있는지는 전달됩니다.

Anti-pattern (이렇게 쓰지 마세요)

"필요에 따라 참조해 주세요"라고 쓰지 마세요. 읽히지 않습니다.

참조 파일 안에서 다시 다른 파일을 참조하게 만들지 마세요.

매번 반드시 읽어야 하는 핵심 절차를 외부에 분리하지 마세요.

스크립트: 판단시키고 싶지 않은 처리를 코드로 만들기

Context (전제)

절차가 고정되어 있는 처리는 스크립트를 동봉하여 실행시키는 편이 안정적입니다. 매번 코드를 생성하게 하면 조금씩 다른 결과물이 나오기 때문입니다.

Practice (이렇게 작성하세요)

태스크의 성질에 따라 지시의 세밀함을 바꿉니다.

스크립트에 대해서는 실행시키고 싶은 것인지 읽게 하고 싶은 것인지를 명시합니다. 같은 파일이라도 의도가 두 가지가 있어 혼동되면, 실행하기를 원하는 상황에서 내용을 읽고 재구현을 시작합니다.

• 실행시키고 싶은 경우: "scripts/validate.py를 실행해 주세요"
• 참고하게 하고 싶은 경우: "추출 로직은 scripts/extract.py를 참조해 주세요"

에러 처리(Error handling)는 스크립트 측에 맡깁니다. "실패하면 호출 측에서 대처한다"라고 작성하면, 거기서부터 자기 방식의 복구 처리가 시작되기 때문입니다. 예상되는 실패는 스크립트 내에서 처리하여 정상 계통으로 되돌리거나, 원인을 알 수 있는 메시지를 내보내고 중단합니다.

생성 → 검증 → 수정 → 재검증이라는 루프를 절차로서 작성해 둡니다. 검증을 스크립트로 만들어 두면 품질 판단이 흔들리지 않습니다.

Anti-pattern (이렇게 작성하지 마세요)

매번 스크립트를 생성하게 하지 않습니다.

상수의 근거를 적지 않은 채로 두지 않습니다. TIMEOUT = 47

과 같은 값은 왜 그 값인지 알 수 없다면, 변경해도 되는지 판단할 수 없습니다.

선택지를 나열하지 않습니다. 기본값(Default)을 하나 정하고, 예외적인 케이스만 작성합니다.

강한 표현: 이유와 함께 작성하기

Context (전제)

MANDATORY

MUST

"절대로"와 같은 강한 어조는 무심코 늘어나기 쉽습니다.

하지만 강한 어조만 늘려봤자 별로 효과가 없다는 인상을 줍니다. 모든 스킬이 "내가 최우선"이라고 주장하기 시작하면, 결국 무엇을 우선해야 할지 결정할 수 없게 됩니다.

Practice (이렇게 작성하기)

왜 그렇게 해야 하는지를 이유로서 작성합니다.

이는 기존 스킬에서도 공통적으로 볼 수 있는 작성 방식이었습니다. 강한 어조를 나열하기보다, 그 지시가 필요한 이유를 덧붙인 것이 많았으며, 그것이 예상치 못한 상황에 직면했을 때도 판단이 가능하기 때문이라고 이해하고 있습니다.

Anti-pattern (이렇게 작성하지 마세요)

강한 어조만 중첩하지 않습니다. 쓰고 싶어진다면, 그 단어를 지우고 이유로 대체할 수 없는지 먼저 생각합니다.

요약

마지막으로, 지금까지의 내용을 카테고리별로 정리합니다.

구성 결정 방법

• 분할은 행 수가 아니라, 독립된 분기(Branch)가 있는지 여부로 판단한다
• 절차가 일직선이라면, 길더라도 하나의 파일로 합친다
• 입구(Entry) 스킬에는 처리를 담지 않고, 분류(Routing)만 작성한다
• 분류 조건은 하나의 표로 정리한다
• 자식 스킬이 해결할 수 없는 경우의 대체 경로를 작성해 둔다

호출 제어 방법

• description에는 "언제 호출할지"뿐만 아니라 "언제 호출하지 말지"를 구체적인 예시와 함께 작성한다
• 발화(Trigger) 방침에는 그 이유를 세트로 작성한다
• 적극적으로 발화시키는 경우에는 멈추는 방법도 작성한다
• 멈추는 범위는 대화 단위가 아니라 요청(Request) 단위로 한다
• 유사한 기능의 스킬끼리는 서로 "자신이 아닌 케이스"를 명시적으로 작성한다
• 명시적으로 로드되는 말단(Leaf) 스킬에서는 description을 생략한다

파일 관리 방법

• 상세 내용은 참조 파일로 분리하여, 필요할 때만 읽게 한다
• 참조는 "읽어라"가 아니라 "읽기 전에 다음 행동을 하지 마라"라고 작성한다
• 참조 파일은 1계층(1-level)까지만 유지한다
• 판단하게 하고 싶지 않은 처리는 스크립트로 만들어 동봉한다
• 스크립트는 실행시키는 것인지 읽게 하는 것인지를 명시한다

작성 방식 및 표현

• description은 3인칭으로 작성한다
• frontmatter는 name과 description만 둔다
• 지시는 능동태로, 동사를 사용하여 작성한다
• 강한 어조는 이유와 세트로 작성한다

스킬은 한 번 작성하고 끝나는 것이 아닙니다.

제대로 호출되지 않은 케이스, 반대로 폭주(Over-trigger)한 케이스를 description에 하나씩 추가해 나가는 것이 결국 가장 빠르게 안정화되는 길입니다.

참고

Discussion