이 문서는 Anthropic에서 Claude Code의 skills를 구축하고 확장하면서 얻은 교훈을 설명합니다. skills는 Claude Code 내에서 가장 많이 사용되는 확장 지점 중 하나이며, 유연하고, 만들기 쉬우며, 배포하기 쉽지만, 어떤 skill이 가장 효과적인지 결정하기 어렵다는 문제를 제기합니다. Anthropic 내부에서는 수백 개의 skill이 활발하게 사용되고 있으며, 이를 통해 개발 가속화를 위한 경험적 지식을 축적했습니다.

Skills의 정의 및 구조:
skills는 단순히 markdown 파일이 아니라, 에이전트가 발견하고 사용하여 작업을 더 정확하고 효율적으로 수행할 수 있도록 돕는 instructions, scripts, resources를 포함하는 folders입니다. skills는 또한 dynamic hooks 등록을 포함한 다양한 configuration options을 가집니다. 효과적인 skills는 이러한 configuration options과 folder structure를 잘 활용합니다.

Skills의 아홉 가지 유형:
Anthropic은 내부 skills를 분류하여 다음 아홉 가지 범주로 나눴습니다. 각 skill은 하나의 범주에 명확하게 속할 때 가장 효과적입니다.

1. Library and API reference: 내부 라이브러리 또는 일반적인 CLI, SDK의 올바른 사용법을 설명합니다. reference code snippets와 gotchas를 포함합니다. 예: billing-lib, internal-platform-cli.
2. Product verification: 코드 작동 여부를 테스트하거나 확인하는 방법을 설명합니다. Playwright, tmux와 같은 외부 tools와 함께 사용되며, Claude의 output quality에 가장 큰 영향을 미쳤습니다. video recording이나 programmatic assertions 같은 기법을 포함합니다. 예: signup-flow-driver.
3. Data fetching and analysis: 데이터 및 모니터링 스택에 연결합니다. 데이터 fetching을 위한 라이브러리, 특정 dashboard IDs, 일반적인 워크플로우를 포함합니다. 예: funnel-query, grafana.
4. Business process and team automation: 반복적인 워크플로우를 자동화하는 skills입니다. 비교적 간단한 instructions을 포함하며, 이전 실행 결과를 log files에 저장하여 일관성을 유지하고 모델이 반성할 수 있도록 합니다. 예: standup-post, $create-<ticket-system>-ticket$.
5. Code scaffolding and templates: 코드베이스 내 특정 기능에 대한 framework boilerplates를 생성합니다. scripts와 결합될 수 있으며, natural language requirements가 있는 경우 유용합니다. 예: $new-<framework>-workflow$, create-app.
6. Code quality and review: 조직 내 code quality를 적용하고 code review를 돕습니다. deterministic scripts 또는 tools를 포함할 수 있으며, hooks 또는 GitHub Action의 일부로 자동 실행될 수 있습니다. 예: adversarial-review, code-style.
7. CI/CD and deployment: 코드베이스 내에서 코드를 fetch, push, deploy하는 데 도움을 줍니다. 다른 skills를 참조하여 데이터를 수집할 수 있습니다. 예: babysit-pr, $deploy-<service>$.
8. Runbooks: 증상(Slack thread, alert, error signature)을 받아들여 multi-tool investigation을 수행하고 구조화된 보고서를 생성합니다. 예: $<service>-debugging$, oncall-runner.
9. Infrastructure operations: 일상적인 유지보수 및 운영 절차를 수행하며, guardrails가 필요한 파괴적인 작업도 포함합니다. 예: $<resource>-orphans$, cost-investigation.

Skills 제작을 위한 팁 (Core Methodology 포함):

• 명백한 것을 진술하지 마십시오: Claude는 코드를 작성하고 코드베이스를 읽을 수 있으므로, 이미 알고 있는 정보를 반복하는 대신 Claude의 일반적인 사고방식을 벗어나게 하는 정보에 집중합니다.
• Gotchas 섹션 구축: Claude가 skill을 사용할 때 흔히 겪는 failure points를 기반으로 gotchas 섹션을 작성합니다. 이는 skill의 highest-signal content입니다.
• 파일 시스템 및 점진적 공개 (Progressive Disclosure) 활용: skill은 folder이며, SKILL.md는 특정 상황에서 Claude가 참조할 수 있는 다른 파일(scripts, assets, data 등)을 가리킵니다. 전체 file system을 context engineering의 형태로 활용하여 Claude에게 skill 내의 파일을 알리고, 적절한 시기에 읽도록 지시합니다. 예를 들어, 상세한 함수 시그니처는 references/api.md에, 결과물 템플릿은 assets/에 둘 수 있습니다.
• Claude를 억압하지 마십시오: Claude는 일반적으로 지시를 따르려 하므로, 너무 구체적인 지시 대신 상황에 적응할 수 있는 유연성을 제공합니다.
• 설정(Setup) 고려: skill이 사용자로부터 context를 필요로 하는 경우, config.json과 같은 file에 설정 정보를 저장하고, 설정되지 않은 경우 에이전트가 사용자에게 정보를 요청하도록 합니다. 구조화된 질문을 위해 AskUserQuestion tool을 사용할 수 있습니다.
• 모델을 위한 설명 작성: Claude Code가 세션을 시작할 때, 모든 사용 가능한 skill의 description을 나열합니다. Claude는 이 목록을 스캔하여 요청에 적합한 skill이 있는지 결정하므로, description은 skill이 언제 트리거되어야 하는지에 대한 설명이어야 하며, trigger keywords를 포함하는 것이 좋습니다.
• Claude가 기억하도록 돕기: 일부 skill은 append-only text log file이나 JSON files, 또는 SQLite database와 같은 형태로 데이터를 저장하여 memory를 가질 수 있습니다. 이는 과거 이벤트를 기억하고 다음 실행 시 변경 사항을 인식하는 데 도움을 줍니다. CLAUDE_PLUGIN_DATA 환경 변수를 사용하여 데이터를 저장할 안정적인 디렉토리를 얻을 수 있습니다.
• 스크립트 저장 및 코드 생성: scripts와 라이브러리를 Claude에게 제공하면, Claude는 boilerplate를 재구성하는 대신 composition에 집중하고 다음에 무엇을 할지 결정할 수 있습니다. 예를 들어, 데이터 과학 skill은 이벤트 소스에서 데이터를 가져오는 함수 라이브러리를 포함할 수 있습니다.
• On-demand Hooks 사용: skill은 skill이 호출될 때만 활성화되고 세션 기간 동안만 지속되는 hooks를 포함할 수 있습니다. 이는 항상 실행되기를 원치 않지만 특정 상황에서 매우 유용한 opinionated hooks에 사용됩니다. 예: careful (rm -rf 등을 차단), freeze (특정 디렉토리 외 Edit/Write 차단).

Skills 배포 및 관리:
skills는 repos (./.claude/skills)에 체크인하거나, Claude Code Plugin marketplace를 통해 배포할 수 있습니다. 소규모 팀의 경우 repo에 체크인하는 것이 유용하지만, scale이 커지면 internal plugin marketplace를 통해 skills를 배포하고 팀이 어떤 skill을 설치할지 결정하도록 할 수 있습니다. Anthropic은 중앙 집중식 결정 대신 sandbox folder에 skill을 업로드하고 traction을 얻으면 marketplace로 PR을 제출하는 방식으로 skills를 관리합니다.

Skills 조합 및 측정:
skills 간의 종속성 관리는 현재 marketplaces나 skills에 내장되어 있지 않지만, 다른 skills를 이름으로 참조하여 모델이 설치되어 있는 경우 호출하도록 할 수 있습니다. skill usage를 측정하기 위해 PreToolUse hook을 사용하여 skill 사용량을 로깅하고, 인기가 있거나 예상보다 적게 트리거되는 skills를 식별할 수 있습니다.

skills best practices는 계속 발전하고 있으며, 많은 효과적인 skills는 소수의 코드와 gotcha로 시작하여 Claude가 새로운 edge cases에 부딪힐 때마다 개선되었습니다.