Skill 작성의 다양한 접근 방법

0. 도입 — Prompting · Custom Command · Skill

스킬을 이해하는 가장 빠른 길은 그 앞 단계와 비교해 보는 것이다. 셋 다 "지시를 재사용한다"는 목적은 같지만, 누가 쓸지 정하고, 얼마나 오래 남고, 무엇을 담을 수 있는지가 다르다.

• Prompting — 대화 안에서 한 번 쓰고 마는 지시. 매번 직접 써 줘야 하고 대화가 끝나면 사라진다. 자유도는 가장 높지만, 반복해서 입력하는 수고도 가장 크다.
• Custom command (슬래시 커맨드) — 자주 쓰는 프롬프트를 템플릿으로 저장해 두고 /이름으로 사용자가 직접 호출한다. 타이핑 수고는 줄지만 "언제 쓸지"는 여전히 사람이 판단하고, 들어가는 내용도 대체로 텍스트 한 덩어리다.
• Skill — 관련 있어 보일 때 모델이 알아서 골라 쓴다. description으로 발견되고, 필요할 때만 읽히며, 절차·스크립트·자료를 여러 파일로 묶어 대화가 바뀌어도 다시 쓴다.

	Prompting	Custom Command	Skill
언제 쓸지 결정	사람 (그때그때)	사람 (직접 호출)	모델 (스스로 선택)
지속성	한 번뿐	재사용 (수동)	재사용 (자동 발견)
담는 것	텍스트 한 덩어리	템플릿 하나	여러 파일 + 스크립트 + 단계적 공개

표는 각 방식의 기본값 기준이고, 실제 경계는 이보다 흐리다: 스킬도 사용자가 콕 집어 부를 수 있고("X 스킬 써줘"), 구현에 따라 커맨드도 파일 참조나 셸 실행을 품을 수 있다. 본질적인 차이는 담는 내용의 형태보다 "언제 쓸지를 기본적으로 누가 판단하는가 — 사람인가 모델인가" 에 있다.

정리하면, 스킬은 prompting → custom command의 연장선에서 "모델이 알아서 꺼내 쓰는, 여러 파일로 된 재사용 가능한 능력" 으로 한 걸음 더 나간 형태다. 그만큼 "무엇을 어떻게 담을지" 정할 거리가 많아지고, 그래서 아래 네 축이 필요해진다.

---

1. 네 가지 축 — 한눈에

스킬 만들기에 대한 조언은 뒤섞어 놓으면 헷갈리지만, 다음 네 축으로 나누면 하나씩 따로 결정할 수 있다.

축	질문	성격
① Origination	내용을 어디서 가져오는가	담을 내용의 출처
② Authoring	어떻게 만들고 검증하는가	만드는 과정
③ Structure	어떻게 구조를 잡는가	담는 형식
④ Freedom	지시를 얼마나 조이는가	지시의 강도

①이 "담을 내용이 어디서 오는가"라면, ②③④는 그와 별개로(그래서 "직교") 고를 수 있는 "어떻게"의 축이다. 같은 내용이라도 만드는 과정·구조·자유도는 따로 정할 수 있다.

①과 ②는 헷갈리기 쉬우니 주의. 가르는 기준은 시점이다: ①은 첫 초안의 내용이 어디서 오는가이고, ②는 초안이 생긴 뒤 어떤 과정으로 검증하고 다듬는가다. 예를 들어 "평가/갭 주도"는 eval을 먼저 정해 초안을 끌어내는 한에서 ①이고, 그렇게 만든 초안을 A/B 루프로 돌려 가며 다듬는 활동은 ②다. 실제 작업에서는 둘이 자연스럽게 이어지지만, 결정 자체는 따로다 — 설계형(①)으로 시작한 스킬을 A/B 루프(②) 없이 내놓을 수도 있고, 그 반대도 된다.

---

2. ① Origination — 내용을 "어디서" 가져오는가

같은 스킬이라도 내용이 실제 해 본 경험에서 나오느냐(귀납), 목표에서 미리 설계되느냐(연역) 에 따라 성격이 갈린다. 이 축은 그 사이에 펼쳐진 스펙트럼이다.

방식	설명	SW 개발로 치면
추출형 (Extraction)	여러 번 해 본 실제 작업에서 공통 절차를 뽑아냄	리팩터링 (일 끝난 뒤 추출)
설계형 (Design)	목표에서 거꾸로 절차를 설계해 미리 정해 둠	아키텍처 설계 (일 시작 전 규정)
이식형 (Porting)	기존 문서(런북·SOP·스타일 가이드·API 문서)를 스킬 형식으로 옮김	레거시 래핑 / 어댑터
실패기반 (Failure-driven)	자꾸 반복되는 실수를 막는 "하지 말 것"에서 출발	버그 수정 + 회귀 테스트
예시기반 (Example-based) †	절차 대신 잘된 결과물 예시로 패턴을 따라가게 함	TDD / 예시 기반 명세, few-shot
창발형 (Spike-then-harvest)	이것저것 해 보다가 좋은 방법이 나오면 굳힘	애자일 spike / 프로토타이핑
평가/갭 주도 (Evaluation-driven)	측정할 수 있는 실패 기준(eval)을 먼저 정하고, 거기서 거꾸로 만듦	TDD (테스트 먼저)
에이전트 위임 (Agent-authored) ‡	스킬 작성 자체를 모델에게 맡김	코드 생성 / 메타프로그래밍

† 예시기반은 출처(①)이면서 동시에 "무엇으로 담는가"라는 ③ Structure의 선택이기도 하다 — 두 축에 걸친 항목이니 유의.
‡ 에이전트 위임은 따지고 보면 "어디서"가 아니라 "누가 만드는가" 의 문제라 ② Authoring의 주체 선택에 가깝다. 다만 모델이 이미 아는 지식이 내용의 출처가 된다는 점에서, 관례를 따라 여기서 함께 다룬다.

어느 것을 고르나 — 상황별 안내

지금 손에 있는 것	권하는 출발점
이미 여러 번 해 본 작업 기록	추출형 — 있는 기록에서 뽑는 게 가장 싸다
검증된 런북·SOP·스타일 가이드	이식형 — 새로 쓰지 말고 옮겨 담는다
자꾸 눈에 밟히는 특정 실수	실패기반 → 쌓이면 평가/갭 주도로 키운다
아무것도 없고 요구만 있음	평가/갭 주도 — eval을 정하는 일이 곧 요구를 분명히 하는 일이다
절차로는 못 쓰겠지만 잘된 예시는 있음	예시기반 — 단, ③에서 예시를 참조 파일로 담는다

꼭 하나만 골라야 하는 것은 아니다 — 이식형으로 시작하되 검증은 평가 주도로 하는 식의 조합이 오히려 흔하다.

가장 자주 등장하는 방식 — 평가/갭 주도

여러 출처에서 가장 자주 반복되는 방식이다. 공식 가이드가 권하는 순서:

1. 대표 과제로 에이전트를 돌려 어디서 막히는지 지켜본다
2. 스킬 없이 돌린 baseline을 먼저 확보한다
3. 최소한의 지시만 쓴다
4. 지켜본 것을 근거로 조금씩 보탠다

"실패기반"을 일반화한 것으로, SW의 TDD 에 그대로 대응한다. 추출/설계라는 두 극단과는 또 다른 세 번째 길이다.

두 번째로 자주 보이는 것은 에이전트에게 맡기는 방식 — 요즘 에이전트는 스킬 형식을 원래부터 알고 있어서, "스킬로 만들어 줘" 한마디에 그럴듯한 frontmatter와 본문을 뽑아낸다.

참고 — 이 축을 한 문장으로 꿰는 시각: 설계형은 목표에서 수단으로(causation) 가고, 추출·이식·창발·평가주도는 손에 있는 재료 — 이미 해 본 작업, 기존 문서, 눈에 띈 실패 — 에서 목표로(effectuation) 간다. 앞서 말한 연역/귀납의 다른 이름일 뿐이니 새로 외울 필요는 없다.

---

3. ② Authoring — 어떻게 만들고 검증하는가

2-에이전트 A/B 루프 (가장 널리 쓰이는 과정)

• Claude A: 스킬을 쓰고 고친다
• Claude B: 스킬을 얹은 채 (테스트 시나리오가 아닌) 실제 과제를 푼다
• 루프: B가 쓰는 모습을 지켜본다 → 막히거나 뜻밖으로 움직이는 지점을 적어 둔다 → A에게 가져가 고친다

SW로 치면 페어 프로그래밍 + 코드 리뷰다. 핵심은 짐작이 아니라 직접 지켜본 행동을 근거로 고친다는 점.

지켜볼 것들

• 예상과 다른 읽기 순서: 파일을 엉뚱한 순서로 읽는다면, 구조가 직관적이지 않다는 신호
• 못 따라간 연결: 참조 파일로 넘어가지 못하면, 링크를 더 또렷하게
• 한 파일만 계속 읽음: 같은 파일을 자꾸 다시 연다면, 그 내용을 SKILL.md 본문으로 올리는 것을 고려
• 한 번도 안 읽는 파일: 필요 없거나, 읽어야 할 이유가 전달되지 않고 있다는 뜻

---

4. ③ Structure — 어떻게 구조를 잡는가 (Progressive Disclosure)

쓰지 않을 때는 토큰을 차지하지 않게 하는 3단계 구조:

1. Level 1 — 메타데이터: 시작할 때는 모든 스킬의 name + description만 시스템 프롬프트에 올라간다
2. Level 2 — 본문(SKILL.md): 관련될 때만 읽힌다. 권장 500줄 이하 — 트리거될 때마다 전체가 컨텍스트에 실리기 때문인데, 이 상한에 가까워지면 문장을 쥐어짜기보다 한 단계 더 나눠 Level 3로 내려보내는 것이 맞다
3. Level 3 — 참조 파일·스크립트: 필요할 때만 읽힌다. 스크립트는 읽지 않고 실행할 수 있어 출력만 토큰을 쓴다

전형적인 구조의 예 (여러 도메인을 지원하는 배포 스킬):

cloud-deploy/
├── SKILL.md            # 작업 흐름 개요 + "어느 참조를 언제 읽을지" 안내   (Level 2)
├── references/
│   ├── aws.md          # 해당 도메인일 때만 읽힘                         (Level 3)
│   └── gcp.md
└── scripts/
    └── validate.py     # 읽지 않고 실행 — 출력만 컨텍스트에 들어옴        (Level 3)

모델은 관련 있는 참조 하나만 읽는다 — 함께 쓰일 일 없는 내용을 파일로 나눠 두면, 안 쓰는 쪽의 토큰이 0이 되기 때문이다.

구조를 잡을 때의 원칙

• SKILL.md가 비대해지면 나눈다. 함께 쓰일 일이 없거나 드물게만 필요한 내용은 경로를 나눠 토큰을 아낀다
• 참조는 한 단계 깊이까지만 둔다. 이유: 모델이 참조의 참조까지 끝까지 따라간다는 보장이 없어서, A→B→C처럼 이어지면 C가 안 읽힌 채 작업이 진행되는 부분 로딩이 생긴다 — 이런 문제는 지시가 원래 없었던 경우와 구분이 안 돼 원인 찾기가 어렵다
• 코드는 실행할 도구이기도 하고 읽을 문서이기도 하다 — 어느 쪽으로 쓰라는 것인지 분명히 해 둔다
• SKILL.md는 온보딩 가이드의 목차처럼, 자세한 자료로 안내하는 개요여야 한다

Description이 발견을 좌우한다

• 스킬이 안 불려 온다면, 문제는 대개 본문이 아니라 description이다
• 3인칭으로 무엇을 + 언제 쓰는지 모두 적는다 — description은 사용자가 아니라 스킬 목록을 훑는 모델이 읽는 글이라, 도구 카탈로그의 한 줄처럼 써야 잘 걸린다
  • 나쁨: "PDF 관련 스킬." — 무엇을 하는지도, 언제 쓰는지도 없다
  • 좋음: "PDF 읽기·병합·양식 채우기를 처리한다. 사용자가 .pdf 파일을 올리거나 언급하면, 다른 요청 같아 보여도 일단 이 스킬을 쓴다." — 무엇+언제가 다 있고, 끝 문장이 살짝 들이댄다
• 모델은 스킬을 덜 쓰는 쪽으로 치우치는 경향이 있어서, 조금 들이대는(pushy) 문구가 오히려 낫다
• 글자 수 제한(작성 시점 기준 개방형 스펙 1024자 / Claude Code 목록 약 1536자 — 구현마다 다르고 바뀔 수 있음) 안에서 트리거 조건·제외 조건·키워드가 자리를 다툰다

---

5. ④ Freedom — 지시를 얼마나 조이는가 (Control Tuning)

얼마나 조일지는 그 작업이 얼마나 잘 깨지는가(fragility) 에 맞춘다.

• 모든 행동을 순서대로 못 박으면 → 상황 판단이 중요한 작업을 망친다
• 느슨한 안내만 주면 → 한 단계만 어긋나도 무너지는 절차에서 실패한다

선언형(제약형) vs 절차형(레시피)

	선언형 / 제약형	절차형 (레시피)
담는 것	규칙·지켜야 할 조건·정책	단계별 순서
예	"인용은 항상 이 형식", "이 라이브러리 금지"	"먼저 X, 다음 Y…"
SW로 치면	linter 규칙 / 선언형 프로그래밍	명령형 스크립트

"무조건 ~하라"의 함정

• ALWAYS / NEVER / MUST를 남발하는 것은 경고 신호다
• 규칙만 달랑 주면, 예상 못 한 경우를 놓치거나 융통성이 필요한 곳까지 규칙을 밀어붙이게 된다
• "규칙 + 이유" 로 쓴다 → 그 이유가 예상 밖 상황에서 판단 기준 노릇을 한다
  • 나쁨: "MUST use constructor injection. NEVER use field injection."
  • 좋음: "constructor injection을 쓴다. field injection은 Spring 컨텍스트 없이는 mock을 만들 수 없어 테스트하기 어려워지기 때문."
• 다만 설명은 토큰을 잡아먹는다. 정말 잘 깨지는 단계라면 짧고 단호한 명령이 여전히 낫다

---

6. 경계 조건 — 만들지 않기, 유지하기, 조합하기

네 축은 "어떻게 만들까"에 답하지만, 실무에서는 그 앞뒤에 놓인 세 가지 질문이 성패를 가르곤 한다.

6.1 스킬을 만들지 말아야 할 때

스킬은 공짜가 아니다 — description은 늘 컨텍스트 한구석을 차지하고, 본문은 불릴 때마다 토큰을 쓰며, 관리할 거리도 하나 늘어난다. 다음 신호가 보이면 만들지 않는 편이 낫다:

• 한 번 쓰고 말 일: 다시 쓸 일이 없으면 prompting으로 충분하다 (§0 스펙트럼의 왼쪽에 머무를 것)
• 모델이 이미 잘하는 일: 스킬 없이 돌린 baseline이 이미 목표를 채운다면, 스킬은 토큰 낭비를 넘어 군더더기 지시로 오히려 결과를 나쁘게 만들 수 있다. §2에서 "baseline부터"라고 한 데는 이런 뜻도 있다 — baseline은 저작 순서이기 이전에, 만들 필요가 있는지를 가리는 시험이다
• "언제 쓰는지"를 말로 적을 수 없는 일: 트리거 조건을 description으로 쓸 수 없다면 모델도 쓸 때를 판단할 수 없다. 이럴 땐 부르는 시점을 사람이 아는 custom command가 낫다

6.2 유지보수 — 자유도는 한 번 정하고 끝이 아니다

④ Freedom의 기준인 "잘 깨지는 정도"는 모델 실력에 따라 달라진다. 오늘은 잘 깨져서 꽉 조인 절차가 필요했던 단계가, 다음 모델 버전에서는 알아서 하게 둬도 되는 단계가 된다. 그래서:

• 모델 업그레이드는 스킬의 조임 정도를 다시 볼 때다 — 절차형 지시가 새 모델의 더 나은 기본기를 오히려 막고 있지 않은지, baseline을 다시 떠 본다
• 스크립트나 외부 API에 기대는 스킬은 그쪽이 바뀌면 소리 없이 깨진다. §2에서 만든 eval을 버리지 말고 회귀 테스트로 계속 돌리면 두 경우 모두 잡아낼 수 있다

6.3 스킬끼리의 조합과 충돌

스킬이 쌓이면 새로운 문제가 생긴다:

• 트리거 경합: description이 비슷한 스킬끼리 서로 호출을 가로챈다. description에 쓰는 조건만이 아니라 빼는 조건("~에는 쓰지 말 것")도 넣는 이유가 이것이다
• 지시 충돌: 한 과제에 스킬 둘이 같이 실리면 서로 어긋나는 규칙이 만날 수 있다. "다른 스킬은 없다"고 가정하고 쓰지 말고, 규칙에 이유를 달아 두면(§5) 부딪혔을 때 모델이 무엇을 앞세울지 판단할 근거가 남는다
• 복제냐 참조냐: 여러 스킬이 함께 쓰는 절차는 복사하지 말고 한 곳에 두고 링크한다 — SW의 DRY 원칙과 같다. 다만 "참조는 한 단계"(§4) 원칙과 부딪히므로, 공유하는 스킬이 둘뿐이라면 그냥 복사해 두는 쪽이 오히려 싸다

---

7. 요약 / 결론

• 스킬이 앞 단계들과 갈리는 본질은 언제 쓸지를 모델이 판단한다는 데 있고(§0), 바로 그래서 만들 때 설계가 필요하다 — 사람이 부르는 커맨드와 달리, 발견·로딩·해석을 전부 글로 풀어 둬야 하기 때문이다.
• 그 설계는 뒤섞지 말고 네 축을 하나씩 정하는 일이다: ① 어디서 가져올까(Origination) ② 어떻게 만들까(Authoring) ③ 어떻게 담을까(Structure) ④ 얼마나 조일까(Freedom).
• Origination에서 문헌이 가장 힘주어 말하는 것은 평가/갭 주도(TDD) 로, SW의 테스트 우선 개발과 같다.
• 네 축의 앞뒤에는 세 가지 경계 질문이 있다: 만들 가치가 있는가(baseline이 가려 준다), 모델이나 의존성이 바뀌면 어떻게 지키는가(eval을 회귀 테스트로), 다른 스킬과 어떻게 같이 사는가(빼는 조건과 이유 달린 규칙).
• 실무는 네 축을 이어 붙인 흐름으로 굴러간다:

갭을 eval로 정의             → ① Origination (평가 주도)
   ↓
A/B 루프로 만들고 검증        → ② Authoring
   ↓
progressive disclosure       → ③ Structure
   ↓
잘 깨지는 정도에 맞춰 조임    → ④ Freedom

한 문장 요약 — 스킬 만들기란 반복되는 지시를 모델이 알아서 꺼내 쓰게 만드는 일이며, 그때 출처·과정·구조·강도를 네 축으로 나눠 따로 정하는 것이 요령이고, 출발점으로는 "실패(eval)부터 정하고 최소한만 채워 반복"하는 평가 주도 방식이 가장 든든하다.

---

참고 출처

• Anthropic Engineering — Equipping agents for the real world with Agent Skills
• Claude Docs / Platform Docs — Skill authoring best practices, Agent Skills overview
• Skill Authoring Patterns from Anthropic's Best Practices (generativeprogrammer.com)
• The SKILL.md Pattern (Bibek Poudel, Medium)
• obra/superpowers — writing-skills/anthropic-best-practices.md