서론

Subagent vs MCP vs Skill에서 우리는 세 축의 지도를 그렸습니다. 스킬(Skill)은 지식 (knowledge) 축을 이동시키고, 서브에이전트 (Subagent)은 **컨텍스트 (context)**를 이동시키며, MCP 서버는 **역량 (capability)**을 이동시킵니다. 이후 우리는 서브에이전트 축에 대한 심층 가이드인 커스텀 에이전트 작성법과 오케스트레이션 실패 모드 (orchestration failure modes)를 발표했습니다. 이 가이드는 마지막 삼인조를 완성합니다. 바로 스킬 (skill) 자체를 어떻게 작성하는가에 대한 것입니다.

스킬은 세 가지 중 가장 과소평가되어 왔는데, 그 이유는

• CLAUDE.md는 모든 상호작용 시 로드됩니다. 이는

1. 산문이 아닌 프로시저(procedure)로 작성하세요. 모델이 순서대로 실행할 수 있는 번호가 매겨진 단계(Numbered steps)가 문맥을 설명하는 긴 단락보다 훨씬 효과적입니다. 예: "1. package.json의 버전을 올립니다. 2. 마지막 태그 이후의 커밋으로부터 changelog를 재생성합니다. 3. ..."
2. 전제 조건(preconditions)과 주의 사항(gotchas)을 인라인(inline)으로 명시하세요. "태깅하기 전에, main 브랜치의 CI가 통과(green)되었는지 확인하세요"와 같이, 사람이라면 당연히 확인했을 법한 내용을 포함하세요.
3. 상세한 내용은 본문에 넣지 말고 참조(point)하세요. 버전 관리 정책이 800단어에 달한다면, 이를 references/versioning.md에 두고 "버전 업 규칙은 references/versioning.md를 읽으세요"라고 작성하세요. 이것이 바로 다음에 설명할 점진적 공개(progressive disclosure)입니다.

점진적 공개 (Progressive Disclosure): SKILL.md를 가볍게 유지하기

스킬 작성의 핵심 전략입니다. SKILL.md는 작아야 합니다. 즉, 트리거(trigger)와 개요(overview), 그리고 참조(pointers)만 포함해야 합니다. 방대한 자료는 작업이 해당 단계에 도달했을 때만 로드되는 보조 파일들에 담아둡니다.

이것이 중요한 이유: 설명과 개요는 라우팅(routing)을 위해 스캔되므로 비용이 저렴해야 합니다. 상세한 2,000단어 분량의 명세서는 스킬이 실제로 활성화되고 작업에 그 정도의 깊이가 필요할 때만 컨텍스트(context)에 포함되어야 합니다. 모든 내용을 인라인으로 포함하는 스킬은 목적에 어긋납니다. 이는 단지 트리거 방식만 다를 뿐, 다시 CLAUDE.md 스타일의 비대화(bloat)로 돌아가는 것입니다.

## Steps
1. 버전 업 (semver 규칙은 references/versioning.md 참조)
2. 초안 생성을 위해 scripts/changelog.sh 실행
...

Claude는 규칙이 실제로 필요할 때만 references/versioning.md를 읽으며, 매번 로드하지는 않습니다.

실전 예시: 릴리스 체크리스트 스킬

---
name: cut-release
description: 릴리스를 생성하거나, 버전을 게시하거나, 빌드에 태그를 달 때 사용합니다. 버전 업, changelog, 태그, 게시, 그리고 CI 통과 전제 조건을 다룹니다.
...

전제 조건과 "중단된 지점을 보고하세요"라는 문구가 이 스킬을 단순한 단계 나열이 아닌, 신중한 사람이 적용하는 가드레일(guardrails)을 갖춘 프로덕션급(production-grade) 스킬로 만들어 줍니다.

실전 예시: 도메인 플레이북 스킬

---
name: debug-flaky-test
description: 테스트가 가끔 통과하거나 실패할 때, 또는 CI의 불안정성(flakiness), 간헐적 실패, 또는 스위트 내의 레이스 컨디션(race conditions)을 조사할 때 사용하십시오.
...

내장된 도메인 지식(네 가지 일반적인 원인)에 주목하십시오. 이는 조직의 전문 지식(institutional expertise)이며, 시니어 엔지니어의 체크리스트를 누구나 실행할 수 있도록 패키징된 것입니다.

흔한 작성 실수 (Common Authoring Mistakes)

• 모호한 설명 (Vague description). 스킬은 존재하지만 전혀 실행되지 않습니다. 사용자가 실제로 필요할 때 입력하는 구체적인 트리거 문구(trigger phrases)를 추가하십시오.
• 모든 것을 CLAUDE.md에 넣기 (Everything in CLAUDE.md). 상황별 프로시저(procedures)가 모든 프롬프트를 비대하게 만듭니다. 이를 스킬(skills)로 옮기십시오.
• 방대한 세부 사항을 인라인으로 작성 (Inlining heavy detail). 2,000단어 분량의 SKILL.md를 만드는 것입니다. 점진적 공개(progressive disclosure) 방식을 사용하십시오. 즉, references/를 참조하도록 안내하십시오.
• 프로시저 대신 산문 사용 (Prose instead of procedure). 에세이처럼 읽히는 스킬입니다. 단계에 번호를 매기십시오.
• 가드레일 부재 (No guardrails). 전제 조건(preconditions)이나 중단 조건(stop conditions)이 없는 단계들입니다. 신중한 사람이 수행할 법한 확인 절차를 추가하십시오.

원칙 (The Principle)

스킬은 **적시 전문 지식 (just-in-time expertise)**입니다. CLAUDE.md는 항상 유효한 내용인 반면, 스킬은 특정한 작업을 수행할 때 유효한 내용입니다. 기술의 핵심은 설명(description)을 통해 적절한 순간에 실행되도록 하는 것과, 점진적 공개(progressive disclosure)를 통해 필요할 때까지 비용을 낮게 유지하는 것입니다. 이 두 가지를 제대로 수행하면 팀의 프로시저는 아무도 열어보지 않는 위키(wiki)에 머물지 않습니다. 작업이 요구하는 바로 그 순간에 모든 기능이 탑재된 상태로 나타나며, 그 외의 시간에는 방해되지 않게 유지됩니다.

프로덕션급 Claude Code 설정하기 (Setting Up Production-Ready Claude Code)

스킬은 안정적이고 공유된 환경에서 가장 빛을 발합니다:

1. 팀 공유 및 CI 호출 워크플로우를 위한 신뢰할 수 있는 호스트. 스킬은 버전 관리(Version-controlled)가 가능하며 CI에서도 실행됩니다. HTStack — 홍콩 VPS, 낮은 지연 시간의 중국 본토 접속, 안정적인 BGP를 제공합니다. dibi8.com을 호스팅하는 것과 동일한 IDC입니다. 월 $5-12 수준입니다.

2. 병렬 실행을 위한 클라우드 여유 공간. DigitalOcean — 60일 동안 사용할 수 있는 $200 무료 크레딧을 제공하며, 14개 이상의 리전(Region)을 보유하고 있습니다.

3. 스킬 번들. 훌륭한 스킬을 작성하는 가장 빠른 방법은 훌륭한 스킬을 읽는 것입니다. 저희는 실전에서 검증된 5개의 스킬을 Gumroad에서 $19 번들로 패키징했습니다. 설명, 단계적 정보 공개(Progressive-disclosure) 구조, 그리고 번들링된 스크립트가 이미 올바르게 구현되어 있습니다.

관련 읽을거리

• Subagent vs MCP vs Skill — 이 가이드가 완성하는 3축 프레임워크(Three-axis framework).
• Custom Agent Authoring — 이 가이드의 서브에이전트 축(Subagent-axis) 형제 가이드.
• AI Agent Skills 2026 Developer Guide — 더 넓은 범위의 스킬 생태계.
• Subagent Patterns — 스킬이 위임된 작업자(Delegated workers)와 결합하는 방식.

결론

Skills는 가장 저렴하면서도 과소평가된 확장 지점(extension point)입니다. 즉, 상황별 전문 지식을 적시의 컨텍스트(just-in-time context)로 전환해 주는 마크다운(markdown) 파일이 담긴 디렉토리입니다. 이 모든 기술은 두 가지로 요약됩니다. 적절한 순간에 실행될 수 있도록 실제 트리거 문구(trigger phrases)를 꽉 채운 설명(description), 그리고 작업이 깊이 있는 내용을 필요로 할 때까지 가볍게 유지되도록 하는 **점진적 공개(progressive disclosure)**입니다. 이 두 가지를 잘 작성한다면, 팀 전체와 모든 CI 실행 시 관련성이 있는 정확한 시점에 무료로 활용할 수 있는 프로시저(procedure)를 패키징한 것입니다. 이로써 지식을 위한 스킬(skill), 컨텍스트를 위한 서브에이전트(subagent), 기능을 위한 MCP 서버(MCP server)라는 삼총사가 완성됩니다.