SKILL.md를 쓸 때마다 같은 실수를 한다

Claude Code의 하네스(harness)에 스킬을 늘려가다 보면, 일종의 작업 피로가 쌓인다.

새로운 SKILL.md를 쓸 때마다 매번 같은 것을 생각한다. 프론트매터(frontmatter) 필드에는 무엇을 넣었는지, description(설명)은 어느 정도 길이가 적절한지, 부작용이 있는 스킬은 disable-model-invocation을 true로 설정해야 했는지——기억에 의존해 재현하기 때문에, 쓸 때마다 포맷이 미묘하게 흔들린다.

가장 뼈아픈 것은 description의 누락이다. 트리거 워드(trigger word)를 넣는 것을 잊거나, 네거티브 트리거(negative trigger, 「Do NOT use for ...」)를 쓰는 것을 잊는다. 그 결과 「스킬을 만들었는데 발화하지 않는다」, 「유사한 용도의 다른 스킬과 충돌한다」는 불량이 나중에 발견된다. 에이전트(agent)의 Markdown 파일도 마찬가지로, tools의 제한을 잊고 모든 툴을 상속한 채 공개해 버리거나, model을 지정하지 않아 비용 효율이 낮은 기본값 상태로 작동시키는 등의 실수가 반복되었다.

이것은 주의해서 쓰겠다고 다짐하는 것만으로는 해결되지 않는다. 스킬이나 에이전트를 만드는 작업 자체를 스킬로 만들어 버리면 된다. 그것이 new-skill과 new-agent다.

이 기사에서 다룰 내용

• new-skill/new-agent라는 스킬·에이전트를 만들기 위한 스킬의 구현을 실제 SKILL.md 정의로부터 정확하게 해설한다
• commands/와 skills/의 사용 구분 기준을 정리한다
• description 작성 방식의 틀(발화 판정의 유일한 재료라는 점의 중요성)을 제시한다
• Bloom 분류에 의한 모델 선택의 간이 판정법을 제시한다
• 이 메타 스킬(meta-skill)이 실제로 만들어낸 스킬·에이전트의 사례를 소개한다

전체상: 하네스를 만들기 위한 하네스

하네스의 구조를 도식화하면 다음과 같다.

new-skill과 new-agent 자신도 스킬이기 때문에, 이 도표는 루프(loop)를 형성하고 있다. 하네스가 하네스 자신을 확장하는 장치를 가지고 있다는 것이 이 기사의 핵심이다.

commands/ と skills/ 의 판단 기준

새로운 메커니즘을 만들고 싶다고 생각했을 때, 첫 번째 분기점은 「어디에 둘 것인가」이다.

• commands/ → Claude Code 공식의 slash command 기능. 짧은 단일 프롬프트의 전달 ( /navi 등)
• skills/ → 하네스 독자적인 SKILL.md 포맷. 프론트매터(frontmatter)로 설정을 가지며, 다단계 워크플로우(workflow)용

판단 기준은 심플하다.

단순한 프롬프트 전달뿐이라면 → commands/
외부 툴 호출이 있다면 → skills/
다단계 절차가 필요하다면 → skills/
...

new-skill과 new-agent 자신도 다단계 생성 절차와 allowed-tools 설정을 가지고 있기 때문에 skills/에 위치한다.

new-skill: SKILL.md를 생성하는 스킬

new-skill의 프론트매터는 다음과 같다.

---
name: new-skill
description: Create a new SKILL.md when user says 'make a skill', 'スキルを作って', or wants to automate a workflow. Do NOT use for editing existing skills, CLAUDE.md/settings.json changes, or agent creation.
...

description 자체가 이미 「What + When + 네거티브 트리거」의 형식을 체현하고 있다는 점에 주목하고 싶다. 새로운 SKILL.md를 생성한다(What), 사용자가 「make a skill」, 「スキルを作って(스킬을 만들어줘)」라고 말했을 때(When), 편집·에이전트 생성에는 사용하지 않는다(네거티브 트리거)——메타 스킬 자체가 모범 답안이 되고 있다.

프론트매터 설계 규칙

new-skill이 생성하는 측의 SKILL.md에 대해, 다음의 판단 기준을 적용한다.

스킬 종류의 판단은 다음과 같이 단순화되어 있다.

사용자가 직접 `/skill-name`으로 호출 → `disable-model-invocation: true`
Claude가 문맥에서 자동 판단하여 사용 → `disable-model-invocation: false` (기본값)
부작용 있음 (파일 생성/커밋/전송) → `disable-model-invocation: true`
...

생성 절차 (6단계)

new-skill은 다음 절차로 생성한다.

• 목적을 확인한다: 어떤 스킬인지, 언제 사용하는지, 부작용이 있는지, 인자(argument)가 필요한지
• 프론트매터(frontmatter)를 설계한다: name / description / when_to_use / disable-model-invocation / allowed-tools
• 바디(body)를 작성한다: 참조 계열이면 불렛 포인트, 태스크 계열이면 절차서, 하이브리드라면 참조 정보 → 절차 순서로 작성
• 파일을 배치한다: 개인 스킬은 skills/<name>/SKILL.md, 프로젝트 스킬은 .claude/skills/<name>/SKILL.md
• settings.json에 권한을 등록한다 (필수)
• 확인 사항을 체크한다

단계 5가 사실 가장 놓치기 쉽다. permissions.allow에 다음을 추가하는 것을 잊으면, /name으로 호출하는 순간 승인 프롬프트가 뜨면서 실행이 중단된다.

"Skill(<name>)",
"Skill(<name>:*)",

이 단계를 수작업으로 하던 시절에는 자주 잊어버리곤 했으나, 메타 스킬(meta-skill)의 절차에 포함시킨 덕분에 누락이 없어졌다. "스킬을 만들었는데 작동하지 않는다"라는 보고의 대부분은 이 등록 누락이 원인이었기에, 체감되는 효과가 매우 크다.

최종 확인은 다음 5가지 항목이다.

• description은 1~2문장으로 명확한가?
• 부작용이 있는 경우 disable-model-invocation: true가 설정되어 있는가?
• allowed-tools는 필요 최소한인가?
• (내용이) 500행 이내인가?
• settings.json의 permissions.allow에 Skill(<name>)을 추가했는가?

new-agent: 에이전트 정의 파일을 생성하는 스킬

new-agent도 동일한 구조를 가진다.

---
name: new-agent
description: Create a new agent .md file when user says 'make an agent', 'エージェントを作って', or needs a specialized AI worker. Do NOT use for skill creation, one-off delegation, or editing existing agents.
...

new-skill이 묘사하는 대상이 워크플로(workflow)인 반면, new-agent는 독립된 도구 권한, 모델, 시스템 프롬프트(system prompt)를 가진 전문 워커(worker)를 만든다.

프론트매터 설계 규칙

에이전트 유형의 판단은 다음과 같다.

읽기 전용 리서치 → tools: [Read, Grep, Glob, Bash], model: haiku
코드 수정 포함 → tools: [Read, Write, Edit, Bash, Grep, Glob]
웹 리서치 → tools: [Read, Write, WebFetch, WebSearch]
...

Bloom 분류로 model 결정하기

new-agent 안에서 가장 활약하는 것이 Bloom 분류 판정표다.

간이 판정은 한 가지 질문으로 집약된다. "절차서(템플릿)가 존재하는가?" → Yes라면 haiku, No라면 sonnet 이상.

실례로, article-reader 에이전트는 "기사를 읽고 의문점을 찾아낸다"라는 정형화된 작업이므로 model: haiku, article-writer는 "개요로부터 기사 구성을 창출한다"라는 창조적 태스크이므로 model: sonnet이 지정되어 있다. 이 판단은 new-agent의 Bloom 분류표를 따르는 것만으로 기계적으로 결정된다.

생성 절차 (5단계)

• 전문성을 확인한다: 어떤 전문가인가, 읽기 전용인가 쓰기 포함인가, 컨텍스트 절약이 필요한가, cross-session memory가 필요한가
• 프론트매터(frontmatter)를 설계한다
• 시스템 프롬프트(system prompt)를 작성한다: 책무 → 실행 절차 → 출력 포맷 → 제약 사항의 구조
• 파일을 배치한다: agents/<name>.md
• 확인 사항을 체크한다

시스템 프롬프트 템플릿은 다음과 같은 형태다.

당신은 <전문 분야>의 전문가입니다.
## 책무
- <주요 태스크 1>
...

에이전트는 세션 시작 시 로드되므로, 추가 후에는 Claude Code의 재시작 또는 /agents 명령어를 통한 확인이 필수적이다. 이 주의 사항도 new-agent의 Step 4에 명시되어 있다.

description의 타입 ── 발화 판정의 유일한 재료

new-skill에도 new-agent에도 공통되는 최중요 규칙이 있다. 발화(triggering) 판정에는 description만이 사용된다. 본문은 판정에 사용되지 않는다.

즉, SKILL.md의 본문에 아무리 정중한 절차를 적더라도, Claude가 "이 스킬을 사용해야 하는가"를 판단하는 재료가 되지 않는다. 판단 재료는 description의 한 문장뿐이다. 이 한 문장을 작성하는 데에는 형식이 있다.

• 길이: 50~200자
• 3요소: What (무엇을 하는가) + When (언제 사용하는가) + 트리거 워드
• 네거티브 트리거(negative trigger)를 반드시 포함: Do NOT use for ...

❌ 나쁜 예: 네거티브 트리거(negative trigger) 없음, When이 모호함

description: 기사를 쓰는 스킬.

✅ 좋은 예: What + When + 트리거 워드 + 네거티브 트리거

...

이것은 실제로 존재하는 article-writer

에이전트의 description

그 자체다. 동일한 기사 집필 계열 에이전트인 article-reviewer는 "Review Zenn articles before publication", article-reader는 "독자 관점에서 의문점을 수집한다"와 같이, 각각의 역할 경계가 네거티브 트리거(negative trigger)를 통해 명확하게 구분되어 있다. 3개의 에이전트가 병존하더라도, description의 형식을 지키기만 하면 오작동(mis-firing)은 일어나기 어렵다.

실제로 탄생한 스킬·에이전트

new-skill / new-agent가 실제 운영에 도입된 이후 탄생한 스킬·에이전트의 일부를 소개한다.

design-critique (skills/design-critique)

4단계 설계 비판 하네스(소크라테스식 문답 → 역시나리오 → DbC 계약화 → 최소 설계)로 design-spec.md를 생성. "설계 하네스", "/design-critique", "설계한 뒤에 구현", "요건 정리해서", "사양을 확정한 뒤에"로 트리거. Do NOT use for writing code
...

test-critique (skills/test-critique)

테스트 비판 하네스를 실행한다. 변증법적 4단계(테제 → 안티테제 → 갭 분석 → 신테제)로 테스트 스위트(test suite)의 포괄성·유효성을 비판적으로 검증하고 개선한다. "테스트 비판 하네스", "/test-critique", "테스트를 비판해줘"
...

article-writer / article-reviewer / article-reader (agents/)

• article-writer: model: sonnet (기사 구성의 창조는 L6)
• article-reviewer: model: sonnet (품질 평가는 L5)
• article-reader: model: haiku, color: cyan (독자 관점의 의문점 수집은 정형 작업에 가까워 L2~L3)

이것들은 모두 new-skill / new-agent의 생성 템플릿에 따라 프런트매터(front matter)가 구성되어 있다. description의 3요소, allowed-tools의 최소 권한, model의 Bloom 분류 판정——수작업으로 작성했다면 맞추기 어려웠을 일관성이 메타 스킬(meta-skill)을 경유함으로써 자동으로 담보된다.

Before/After

Before (메타 스킬 도입 전)

• SKILL.md의 필드를 기억에 의존해 재현하므로, 매번 포맷이 미묘하게 다름
• description에 네거티브 트리거를 쓰는 것을 잊어, 나중에 오작동을 인지함
• settings.json에 대한 권한 등록을 잊어, "만들었는데 작동하지 않음"이 빈번하게 발생
• 에이전트의 model 지정을 감각적으로 결정하기 때문에, 비용과 품질의 균형이 안정되지 않음

After (new-skill/new-agent 도입 후)

• 프런트매터의 틀이 매번 동일한 구조로 생성됨
• description이 "What + When + 네거티브 트리거" 형식에 맞춰 자동으로 구성됨
• settings.json 등록이 Step 5로 절차화되어 누락이 없어짐
• model 선택이 Bloom 분류 판정표를 참조하기만 하면 되는 기계적인 작업이 됨

이는 측정된 수치가 아니라, 생성 프로세스에 절차가 고정됨으로써 얻은 구조적인 개선이다. 매번 생각하며 쓰는 방식에서 템플릿에 정보를 흘려넣는 방식으로 작업의 질이 변한 것이 가장 큰 변화다.

요약

• new-skill / new-agent는 스킬·에이전트를 만들기 위한 스킬이며, 하네스가 하네스 자신을 확장하는 구조로 되어 있다.
• commands/와 skills/의 판단 기준은 "단순한 프롬프트 전달인가, 아니면 다단계·외부 도구 호출인가"로 결정된다.
• description

는 발화 판정의 유일한 재료이며, 「What + When + 트리거 워드 (Trigger Word) + 네거티브 트리거 (Negative Trigger)」를 50~200자 내외로 작성하는 형식이 중요하다. 모델 선택은 Bloom 분류(L1-L3→haiku, L4-L6→sonnet/opus)로 판정하며, 간이 판정은 "절차서가 있는가?"라는 하나의 질문으로 집약된다.

• design-critique, test-critique, article-writer/reviewer/reader 등, 실제로 운용 중인 스킬·에이전트(Agent) 군이 이 메타 스킬(Meta-skill)로부터 탄생하고 있다.

스킬이나 에이전트를 매번 수작업으로 작성하는 것을 그만두고, 만드는 절차 자체를 스킬화하는 것만으로도 하네스(Harness)의 일관성과 발화의 안정성이 크게 달라진다.

좋아요나 댓글로 반응해 주시면 큰 힘이 됩니다!

Discussion