Anthropic 공식 에이전트 스킬 가이드: 6가지 인사이트

에이전트 스킬이 양날의 검이라는 건 다들 알지? 근데 Anthropic에서 스킬 작성 가이드 문서를 업데이트했다는 거 알고 있었냐? 다들 모드(mod) 만드느라 바빠서 못 본 거 아님?

이번에도 10분 투자해서 가이드 핵심 내용 6가지로 요약해 왔다.

1. 스킬 이름은 가급적 동명사(-ing)로 지어라. 제발 스킬 이름을 "utils"나 "data" 따위로 짓지 좀 마. 가이드에서는 processing-pdfs나 analyzing-spreadsheets처럼 스킬이 뭘 하는지 명확하게 보여주는 "-ing" 형태를 추천한다. 명사구(pdf-processing)나 행동명(process-pdfs)도 괜찮긴 한데, 라이브러리 전체에서 일관성만 유지해라.

2. 참조는 딱 한 단계 깊이까지만 유지해라. 모든 참조 파일은 SKILL.md에서 바로 연결되게 만들어야 함. SKILL.md가 다른 파일을 가리키고, 그 파일이 또 다른 파일을 가리키는 식이면 클로드가 앞부분 100자 정도만 읽고 미리보기만 할 수도 있다. 하위 폴더는 괜찮은데, 링크 체인은 만들지 마라.

3. 목차를 넣어라. 가끔 에이전트가 파일이 관련 있는지 확인하려고 앞부분 100줄만 읽을 때가 있다. 핵심 내용이 350줄에 있다면, 맨 위에 목차를 넣어서 계속 읽게 만들어야 함.

4. 평가 기반 개발(evaluation-driven dev)을 해라. 그냥 느낌대로 만들지 말고. 일단 스킬 없이 클로드한테 작업 시켜보고, 어디서 막히는지 확인한 다음, 테스트 시나리오 몇 개 짜서 기준점(baseline)을 잡아라. 그 다음에 딱 필요한 만큼만 수정하는 거다. 참고로 가이드 보니까 아직 자체 평가 기능은 없어서 직접 구현해야 함.

5. 설명을 제품이라고 생각해라. 설명은 항상 로드되고, 클로드가 100개가 넘는 스킬 중에서 네 걸 골라내는 기준이 된다. 설명이 애매하면 절대 안 뽑힘. 참고로 3인칭으로 작성하고, 뭘 하는지랑 언제 써야 하는지를 사용자가 실제로 쓸 법한 키워드랑 같이 적어라.

6. 개인적으로 제일 중요하다고 생각하는 규칙: 점진적 공개(progressive disclosure)가 진리다. 시스템 프롬프트에 규칙을 다 때려 박지 말고, 시작할 때는 이름이랑 설명만 넣어라. SKILL.md는 스킬이 필요할 때만 로드되고, 추가 파일은 진짜 필요할 때만 불러와야 한다. SKILL.md는 500줄 이하로 유지하고 나머지는 다 쪼개라.

문서에 나온 다른 팁 하나 더: 스킬을 사용할 모든 모델에서 테스트해 봐라. Opus에서 잘 돌아가는 게 Haiku에서는 더 자세한 설명이 필요할 수도 있다.

출처: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices