Skills (수정중)
SKILL.md 의 골격(frontmatter + 본문)을 읽고, 스킬을 프로젝트 레벨에 두는 이유를 설명하며, education 의 스킬 14종 카탈로그와 스킬이 코드·안전장치를 어떻게 품는지 파악할 수 있다.FDE 세션 'Skills' 편이 개념(이름 붙은 절차)이라면, 여기선 SKILL.md 구조·카탈로그·안전장치를 코드 수준에서 본다.
1. 스킬 = 폴더 하나 = SKILL.md 한 장
스킬 하나는 .claude/skills/{name}/SKILL.md 파일 하나로 정의된다.
위쪽 --- 사이가 frontmatter(메타데이터), 그 아래가 본문(Claude 가 따라 할 절차)이다.
---
name: dev
description: 개발 서버를 시작합니다. 첫 실행이면 포트 할당 + dev 도메인 세팅까지 자동 진행합니다.
user-invocable: true
---
# Django 개발 서버 시작
...본문(실행 절차)...
| frontmatter 키 | 뜻 | 비고 |
|---|---|---|
name |
스킬 이름 = 슬래시 명령(/dev) |
폴더명과 맞춘다 |
description |
언제 이 스킬을 쓰는지 | 자연어 자동 호출의 키 |
user-invocable |
/이름 으로 직접 부를 수 있나 |
education 스킬은 대부분 true |
argument-hint |
인자 사용법 | 예: release 의 "[--user <계정>] [--skip-migrate]" |
본문은 강의노트와 같은, 사람이 읽는 마크다운이다. Claude 가 이걸 읽고 그대로 수행하므로, 스킬을 잘 쓴다는 건 절차를 명확히 쓰는 것이다.
description 이 자연어 호출을 어떻게 라우팅하고 오발동을 어떻게 막는지는 ES03L05에서 다룬다.
2. 프로젝트 레벨에 두고 git 으로 공유한다
스킬은 프로젝트(.claude/skills/)와 글로벌(~/.claude/skills/) 두 곳에 둘 수 있다.
education 은 전부 프로젝트 레벨이다.
- 프로젝트 레벨 =
.claude/가 git 에 커밋된다 = 팀이pull한 번으로 같은 절차를 쓴다. - 글로벌은 커밋되지 않아 공유가 안 되고, 다른 프로젝트와 섞인다.
뒤집어 말하면 같은 이름의 스킬도 프로젝트마다 자기 사본이라 서로 drift 한다. 그래서 어떤 프로젝트를 작업할 땐 그 프로젝트에 루트를 둔 세션에서 한다.
3. education 스킬 카탈로그 (14종)
성격별로 묶으면:
| 묶음 | 스킬 | 한 줄 |
|---|---|---|
| 개발 루프 | dev · develop · release |
서버 기동 · 스펙 기반 개발 한 사이클 · prod 배포 |
| 강의·문서 | create-lesson · create-diagram · feature-doc · structure-doc |
강의노트 · 인라인 SVG 도식 · 기능 문서 · 구조 문서 |
| 고객 산출물 | client-test-guide · client-usage-guide · manual · create-docx |
테스트 가이드 · 사용 가이드 · 화면 매뉴얼 · Word |
| 공통·메타 | sync-from-template · sync-to-template · update-skill-agent-list |
템플릿↔프로젝트 동기화 · 스킬/에이전트 목록 자동 생성 |
읽는 법: 폴더명 = /명령, frontmatter 의 description 한 줄이면 "언제 쓰는지" 가 90% 잡힌다.
반복 절차가 보이면 여기에 스킬로 추가하는 게 컨벤션이다.
4. 스킬은 코드도 품는다
스킬 폴더엔 SKILL.md 만 있는 게 아니라 실행 파일이 같이 있을 수 있다.
.claude/skills/create-docx/
├── SKILL.md # "Word 만들 땐 이 모듈을 import 해서 써라"
└── create_docx.py # 실제 렌더링 코드
SKILL.md 본문이 "이 파이썬 모듈을 이렇게 호출하라"고 지시하고, Claude 가 그 코드를 가져다 쓴다.
create-lesson·create-diagram 도 같은 구조(SKILL.md + 렌더러/헬퍼)다.
즉 스킬은 절차(말) + 도구(코드)를 한 폴더에 묶는 단위이기도 하다.
5. release 가 박는 안전: 휴먼게이트·상태머신·순서강제
스킬의 진짜 가치는 단계 나열이 아니라 위험한 곳에 안전장치를 강제로 박는 것이다.
.claude/skills/release/SKILL.md 를 보면:
- 휴먼게이트: prod 마이그레이션 직전엔 목록을 보여주고
y/N을 받는다. 헬스체크 실패 시 자동 롤백하지 않고 멈춰 사용자 결정을 기다린다. - 상태머신: 항상 라벨 하나로 끝난다.
RELEASE_OK/SKIP: no-new-commits/BLOCKED: migrate-failed등. - 순서강제: migrate 실패 시 gunicorn 재시작을 하지 않는다. 신 코드 + 구 스키마 사고를 절차가 막는다.
사람이 문서 보고 하면 깜빡할 것을, 스킬은 흐름에 박아 빠뜨릴 수 없게 한다.
마무리
- 핵심 정리: 스킬 = 폴더 +
SKILL.md(frontmatter + 본문). 프로젝트 레벨에 커밋해 팀이 공유한다. 코드를 품고(create-docx), 위험한 곳엔 휴먼게이트·상태머신을 박는다(release). - 주의 사항: 글로벌(
~/.claude)에 만들면 커밋이 안 돼 공유가 끊긴다. 반드시 프로젝트.claude/skills/에. - 다음 시간: Agents.