SKILL.md 작성 시 실제로 쓰는 내용

SKILL.md는 긴 프롬프트가 아니라 실행 시점을 설계하는 로더 규격이다. Anthropic이 2025년 12월 공개한 이 형식은 Claude Code, Kiro, Cursor, Codex CLI 등에서 공통으로 동작하며, 같은 지시문도 어디에 두느냐에 따라 비용과 성능이 갈린다.\n\n1,200라인짜리 단일 SKILL.md를 180라인 본문, 3개의 참고 파일, 1개의 헬퍼 스크립트로 재구성하자 컨텍스트 점유율이 **20%**에서 **7%**로 낮아졌다. 같은 모델, 같은 작업에서도 결과가 달라졌고, 성능 차이는 문장이 아니라 어디에 두었는지에서 나왔다.\n\n런타임은 progressive disclosure로 움직인다.\n\n- Level 1: name과 description이 들어간 frontmatter는 매 턴 로드돼 라우팅 신호가 된다.\n- Level 2: SKILL.md 본문은 스킬이 필요하다고 판단될 때만 읽히며, Anthropic은 대략 500줄을 권장 상한으로 둔다.\n- Level 3: references/와 scripts/는 필요할 때만 읽히거나 실행되며, 출력만 컨텍스트에 들어간다.\n\n비유는 주방이 가장 정확하다. 벽의 메모는 frontmatter, 꺼내 보는 레시피는 본문, 바인더의 특정 페이지는 reference, 믹서는 script다. 이 구조를 지키면 스킬은 거의 비용 없이 대기하다가 필요할 때만 메모리를 쓰고, 어기면 환경 드리프트와 버전 민감성 때문에 조용히 망가진다. 한 모델에서 잘 맞던 설정도 업그레이드 뒤에는 품질이 흔들릴 수 있다.\n\n대표적인 함정은 두 가지다.\n\n- reference 파일에 frontmatter를 넣어 상위 스킬처럼 노출시키고, 문맥 없이 직접 트리거되게 만드는 경우.\n- 모든 지시를 한 SKILL.md에 몰아 넣어 1,200라인짜리 덩어리로 만드는 경우.\n\n결국 SKILL.md 작성의 핵심은 문장력이 아니라 아키텍처다.