나만의 에이전트 스킬 작성하는 법

실제 장애 사례를 바탕으로 나만의 에이전트 스킬 작성하기

나만의 에이전트 스킬을 작성하는 가장 좋은 방법은 실제 발생한 장애 사례에서 핵심을 추출하는 것입니다. 코딩 에이전트가 두 번 이상 잘못 수행한 작업을 찾고, 매번 직접 입력했던 수정 사항을 기록한 뒤, 에이전트가 스스로 불러올 수 있는 SKILL.md 파일로 저장하십시오. 그 이후의 과정은 파일 구조나 스킬 실행 여부를 결정하는 한 줄의 코드와 같은 기계적인 작업일 뿐입니다.

이러한 순서는 매우 중요합니다. 상상만으로 작성한 스킬은 겪어본 적 없는 문제를 문서화하는 것에 불과하며, 모든 세션에서 컨텍스트 비용만 발생시킵니다. 반면, 직접 목격한 장애에서 추출한 스킬은 그 자체로 검증 수단을 포함하고 있습니다. 동일한 작업을 다시 요청하여 에이전트가 이번에는 올바르게 수행하는지 확인하면 됩니다. 만약 스킬의 형식 자체가 생소하다면, 먼저 에이전트 스킬의 정의와 로드 방식을 읽어본 뒤 다시 돌아와 작성하십시오.

에이전트가 두 번이나 실패한 작업부터 시작하기

한 번은 우연입니다. 두 번은 패턴이며, 패턴은 파일로 기록할 가치가 있습니다.

실제 서버에서 반복되는 실패 사례가 있습니다. 에이전트에게 nginx에 리버스 프록시 블록을 추가하도록 요청한다고 가정해 봅시다. 에이전트는 /etc/nginx/conf.d/app.conf을 수정하고 sudo systemctl restart nginx을 실행합니다. 수정 내용에 오타가 있어 nginx가 시작을 거부하고, 사용자가 수정할 때까지 사이트는 중단됩니다.

nginx: [emerg] unknown directive "proxy_pas" in /etc/nginx/conf.d/app.conf:12
Job for nginx.service failed because the control process exited with error code.

채팅에서 이를 수정합니다. 서비스를 건드리기 전에 sudo nginx -t로 설정을 테스트하고, restart 대신 reload을 사용하여 적용합니다. 일주일 후, 다른 작업을 수행할 때 같은 실수가 발생합니다. 두 번째 실수는 신호입니다.

실패가 눈앞에 있을 때 두 가지를 기록하십시오. 입력한 요청과 사용한 단어로 작성한 수정 사항입니다. 이 두 줄이 기술(skill)이 됩니다. 요청은 트리거가 무엇과 일치해야 하는지 알려줍니다. 수정 사항은 전체 내용입니다.

Anthropic의 자체 저작 지침은 이를 최우선으로 둡니다. 기술 없이 대표적인 작업에서 에이전트를 실행하고, 실패 지점을 기록한 뒤, 해당 실패를 해결하는 최소한의 지침을 작성하십시오. 실패 자체가 사양(specification)이므로, 실패 사례로 추적할 수 없는 기술은 보통 아무도 필요로 하지 않는 기술입니다.

동일한 증류 과정의 예시로, Ponytail은 요청한 것보다 훨씬 더 많은 내용을 다시 작성하는 에이전트라는 반복적인 실패를 하나의 기술로 바꿉니다를 읽어보십시오. 직접 작성하기 전에 처음부터 끝까지 읽어볼 수 있습니다.

스킬의 구조

스킬은 필수 파일 하나를 포함하는 디렉터리입니다.

.claude/skills/nginx-config-changes/
├── SKILL.md
├── reference/
│   └── proxy-headers.md
└── scripts/
    └── check-and-reload.sh

SKILL.md는 YAML 형식(Docker Compose 파일과 동일한 설정 형식)으로 작성된 프런트매터 블록이 --- 마커 사이에 위치하며, 그 뒤에 마크다운 형식의 지침이 이어집니다. 위에서 언급한 실패 사례를 해결하기 위한 전체 스킬은 다음과 같습니다.

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
---

## Rules

Run `sudo nginx -t` after every edit under `/etc/nginx`. Do not touch the service until it prints `test is successful`.

Apply the change with `sudo systemctl reload nginx`. Never use `restart`. A reload keeps the running workers serving traffic until the new config parses, so a broken config leaves the site up. A restart stops nginx first, so a broken config takes the site down.

If `nginx -t` fails, fix the file and test again. Never reload a config that failed the test.

For the proxy header defaults this project expects, see [reference/proxy-headers.md](reference/proxy-headers.md).

이 파일은 20줄 미만으로 구성된 완전한 스킬입니다. 각 구성 요소는 다음과 같습니다.

• name: 최대 64자까지 가능하며, 소문자, 숫자, 하이픈만 사용할 수 있습니다. claude나 anthropic이라는 단어는 포함할 수 없습니다. 개인용 또는 프로젝트용 스킬에서 이는 표시용 라벨일 뿐입니다. 실행 명령은 디렉터리 이름에서 결정되므로, 이 스킬은 /nginx-config-changes 명령으로 호출됩니다.
• description: 스킬의 기능과 사용 시점을 설명하며, 최대 1,024자까지 작성할 수 있습니다. 이 줄이 실제 작업을 수행하며, 다음 섹션에서 자세히 다룹니다.
• 본문: 스킬이 실제로 실행될 때만 로드되는 지침입니다.
• reference/: 에이전트가 필요할 때 읽어 들이는 추가 파일입니다. SKILL.md에서 이 파일들을 링크하십시오. 링크는 한 단계 깊이까지만 유지하는 것이 좋습니다. 다른 참조 파일에서 다시 참조되는 파일은 일부만 읽힐 가능성이 있기 때문입니다.
• scripts/: 에이전트가 읽는 대신 실행하는 파일입니다. 출력 결과만 컨텍스트 비용에 포함되므로, 300줄짜리 스크립트라도 비용 부담이 적습니다.

스킬이 해결하려는 동작이 복잡해지면 전체 레이아웃을 갖추게 되며, 성능을 고려한 스킬은 Depth Tree, 게이트 파일 세트, PLAN.md 계약에 공간을 할애하여 작업의 일부가 완료되지 않았음에도 에이전트가 작업을 마쳤다고 보고하는 상황을 방지합니다.

디렉터리를 어디에 배치하느냐에 따라 스킬의 사용 범위가 결정됩니다.

• .claude/skills/<name>/SKILL.md (저장소 내부): 해당 프로젝트에서만 사용 가능하며, 저장소를 복제하는 모든 사용자에게 공유됩니다.
• ~/.claude/skills/<name>/SKILL.md: 사용자의 로컬 머신에 있는 모든 프로젝트에서 사용 가능하며, 다른 사용자에게는 공유되지 않습니다.
• <plugin>/skills/<name>/SKILL.md: 플러그인 내부에 포함되어, 해당 플러그인이 활성화된 모든 곳에서 사용 가능합니다.

mkdir -p .claude/skills/nginx-config-changes 명령으로 스킬을 생성하고 파일을 작성하십시오. Claude Code는 이 디렉터리들을 감시하므로, 기존 스킬을 수정하면 실행 중인 세션에 즉시 반영됩니다. 세션 시작 시 존재하지 않던 최상위 스킬 디렉터리를 새로 생성한 경우에는 세션을 재시작해야 합니다. 세션 시작 시점에는 감시할 대상이 없었기 때문입니다.

description 필드는 파일에서 가장 영향력이 큰 항목입니다

에이전트는 시작 시 모든 사용 가능한 스킬의 name 및 description을 컨텍스트로 불러옵니다. 이때 본문은 불러오지 않습니다. 요청이 들어오면 해당 한 줄이 스킬의 관련성을 판단하는 유일한 기준이 되므로, 모호한 설명 뒤에 완벽한 본문을 작성해도 읽히지 않습니다.

설명은 3인칭으로 작성하십시오. "Nginx를 안전하게 테스트하고 다시 불러옵니다(Tests and reloads nginx safely)"는 적절하지만, "Nginx를 도와드릴 수 있습니다(I can help you with nginx)"는 부적절합니다. 해당 텍스트는 시스템 프롬프트에 삽입되는데, 이때 1인칭을 사용하면 모델이 자기 자신에 대해 말하는 것처럼 인식되기 때문입니다.

설명에는 스킬의 기능과 적용 조건을 모두 포함하십시오. Claude Code는 목록 항목을 1,536자에서 자르므로 중요한 사용 사례를 먼저 배치해야 합니다. 추가적인 트리거 문구와 요청 예시를 위한 선택적 when_to_use 필드가 있으며, 이 역시 동일한 글자 수 제한 내에서 설명 뒤에 추가됩니다.

실제로 입력할 단어를 사용하십시오. description: Helps with nginx는 아무것도 매칭하지 못합니다. 아무도 "helps with"라고 입력하지 않기 때문입니다. 위의 버전은 /etc/nginx, server block, reverse proxy 및 TLS (transport layer security) certificate path을 명시하는데, 이는 해당 스킬을 트리거해야 하는 모든 요청의 어휘와 거의 일치합니다.

설명에 대한 테스트 방법은 다음과 같습니다. 본문을 본 적 없는 사람에게 해당 한 줄과 당신이 입력하려는 요청을 함께 보여주고, 이 스킬이 적용되는지 물어보십시오. 그들이 판단할 수 없다면 모델도 판단할 수 없습니다.

본문은 문맥을 유지할 수 있도록 짧게 유지하십시오

스킬이 호출되면 렌더링된 콘텐츠는 하나의 메시지로 대화에 포함되며 세션이 끝날 때까지 유지됩니다. Claude Code는 이후 턴에서 파일을 다시 읽지 않습니다. 작성하는 모든 줄은 한 번의 답변이 아니라 전체 세션에 대한 비용으로 청구됩니다.

Anthropic은 SKILL.md를 500줄 미만으로 유지하고 세부 사항은 별도의 파일로 분리할 것을 권장합니다. 압축 과정은 이 숫자가 임의로 정해진 것이 아님을 보여줍니다. 대화 내용을 요약하여 컨텍스트를 확보할 때, Claude Code는 각 스킬의 가장 최근 호출을 다시 첨부하고 각 스킬의 처음 5,000 토큰만 유지하며, 가장 최근에 호출된 스킬부터 시작하여 총 25,000 토큰의 예산을 채웁니다. 긴 스킬은 중간에 잘릴 수 있습니다. 여러 개의 긴 스킬은 서로를 완전히 밀어낼 수 있습니다.

따라서 모델이 이미 알고 있는 내용은 작성하지 마십시오. 모델은 nginx가 무엇인지, 리버스 프록시가 어떤 역할을 하는지 알고 있습니다. 모델은 reload보다 restart을 선호한다는 귀하의 내부 규칙을 알지 못하며, 이 파일이 존재하는 유일한 이유는 바로 그 규칙 때문입니다.

스킬이 에이전트에게 번들 스크립트를 실행하도록 지시하는 경우, 스킬이 설치된 위치 어디에서나 경로가 확인될 수 있도록 ${CLAUDE_SKILL_DIR}을 사용하여 경로를 지정하고, 권한 프롬프트에서 실행이 중단되지 않도록 동일한 명령을 미리 승인하십시오.

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/check-and-reload.sh *)
---

승인은 스킬을 호출한 턴에만 적용되며 다음 메시지를 보내면 초기화되므로, 영구적인 권한으로 조용히 변경되지 않습니다.

스킬이 실행되는지 확인하는 방법

스킬이 로드되는 것을 확인하는 것만으로는 에이전트가 스킬을 찾았다는 사실만 알 수 있을 뿐, 답변이 실제로 변경되었는지는 알 수 없습니다. 두 가지를 모두 확인해야 하며, 반드시 새로운 세션에서 테스트하십시오. 스킬을 작성한 세션에는 작성 과정에서 입력한 모든 내용이 컨텍스트로 남아 있어, 파일의 누락된 부분을 가릴 수 있기 때문입니다.

1. 프로젝트에서 claude을 사용하여 새 세션을 시작합니다.
2. 스킬 이름을 언급하지 말고, 평소 업무를 처리하듯 본인의 언어로 요청을 입력합니다.
3. 스킬이 호출되는지 확인합니다. 스킬이 실행되지 않는다면 설명(description)을 수정하십시오. 본문(body)은 아직 문제가 아닙니다.
4. 대조군으로 /nginx-config-changes를 사용하여 수동으로 호출해 봅니다. 수동 호출 시에는 정상적으로 작동하는데 요청 시에는 오작동한다면, 이는 지시 사항의 문제가 아니라 트리거(trigger) 문제입니다.
5. 스킬을 끈 상태에서 동일한 요청을 실행하여 두 답변을 비교합니다. /skills 메뉴에서 해당 스킬을 선택하고, Space을 눌러 상태를 off로 변경한 뒤 Enter을 눌러 저장합니다. 이 작업은 .claude/settings.local.json에 skillOverrides 항목을 기록하며, 완료 후 Space을 다시 누르면 on 상태로 돌아갑니다.
6. 스킬이 트리거되지 않아야 할 요청을 몇 가지 작성하여, 해당 요청 시 스킬이 반응하지 않는지 확인합니다.

이 과정을 자동화하려면 공식 마켓플레이스에서 skill-creator 플러그인을 설치하십시오.

/plugin marketplace add anthropics/claude-plugins-official
/plugin install skill-creator@claude-plugins-official

설치 출력에 Run /reload-plugins to activate.가 표시되면 해당 명령을 실행합니다. 그런 다음 Claude에게 스킬 이름으로 평가를 요청하십시오. 이 플러그인은 테스트 케이스를 스킬 디렉터리 내부의 evals/evals.json에 저장하며, 각 케이스를 별도의 하위 에이전트에서 실행하므로 모든 실행은 깨끗한 컨텍스트에서 시작됩니다. 이후 스킬을 사용했을 때와 사용하지 않았을 때의 비교 결과를 작성합니다. 이것이 바로 스킬이 소모하는 토큰과 시간 대비 성능 향상률을 측정한 정확한 수치입니다.

스킬은 별도의 평가 실행에 의존하지 않고 자체적인 증명 기능을 포함할 수도 있습니다. Old Coder 스킬이 에이전트로 하여금 직접 다시 실행할 수 있는 증거 보고서를 반환하게 만드는 방식이 바로 그것입니다.

실패 유형: 스킬이 전혀 트리거되지 않음

요청을 입력해도 에이전트가 기존의 잘못된 방식을 고수하며 스킬 라인이 나타나지 않는 경우입니다. 다음 항목을 순서대로 확인하십시오.

• 스킬 설명에 스킬의 기능은 명시되어 있으나 사용 시점이 정의되어 있지 않아, 사용자의 요청과 일치하는 부분이 없는 경우입니다.
• 스킬 설명에 사용자가 입력한 단어가 포함되어 있지 않은 경우입니다. 예를 들어 "nginx"라고 입력했다면, 설명에도 nginx라는 단어가 포함되어야 합니다.
• 프런트매터(frontmatter)에 disable-model-invocation: true이 설정되어 있습니다. 이 설정은 스킬 설명을 모델의 컨텍스트에서 완전히 제외하며, 오직 /name를 통해서만 스킬을 호출할 수 있게 합니다.
• 프런트매터의 paths glob 설정이 특정 파일로 활성화를 제한하고 있으며, 현재 작업 중인 파일이 해당 조건에 부합하지 않는 경우입니다.
• 스킬이 시작 디렉터리 하위의 .claude/skills/ 디렉터리에 위치해 있습니다. 해당 디렉터리 내부의 파일을 읽거나 편집하기 전까지는 스킬이 로드되지 않으므로, 그전까지는 스킬을 사용할 수 없습니다.

실패 모드: 스킬이 지속적으로 트리거됨

반대되는 문제는 설명이 너무 광범위하여 관련 없는 작업에서도 스킬이 실행되는 경우입니다. "서버 작업 시 사용"이라는 설명은 서버 저장소 내의 거의 모든 요청과 일치합니다. 이 경우 스킬 본문이 도움을 줄 수 없는 작업에도 로드되며, 세션이 끝날 때까지 컨텍스트에 남아 있게 됩니다.

설명을 실제로 중요한 조건으로 좁히고, 해당 스킬이 다루는 파일이나 명령어를 명시하십시오. 특정 파일에만 적용되는 스킬이라면 paths glob을 추가하십시오. 배포나 커밋처럼 부작용이 있는 작업의 경우 disable-model-invocation: true을 설정하고 /name을 사용하여 직접 호출하십시오. 이렇게 하면 에이전트가 임의로 지금이 배포하기 좋은 시점이라고 판단하는 일을 방지할 수 있습니다.

실패 유형: 규칙 파일에 포함되어야 할 기술

CLAUDE.md 또는 AGENTS.md와 같은 규칙 파일은 모든 세션 시작 시 로드되어 모든 작업에 적용됩니다. 기술 본문은 해당 기술이 실행될 때만 로드됩니다. 빈도가 결정의 핵심입니다. 사용하는 패키지 관리자와 같이 저장소의 모든 작업에 적용되는 사실은 규칙 파일에 두어야 합니다. 위에서 언급한 nginx 규칙처럼 작업의 일부에만 적용되는 절차는 기술(skill)에 두어야 하며, nginx를 수정하지 않는 날에는 아무런 비용이 발생하지 않습니다.

진정한 실패는 이를 두 곳 모두에 넣는 것입니다. 두 복사본은 서로 달라지게 되며, 에이전트가 잘못된 동작을 수행할 때 어떤 복사본을 따랐는지 알 수 없게 됩니다. 각 지침마다 하나의 위치를 선택하십시오. 이미 하나의 위치에만 존재하는 규칙을 에이전트가 무시한다면 이는 다른 문제입니다. 기술로 옮겨서 해결되기를 바라기 전에 무시된 지침의 작동 원리를 확인하는 것이 좋습니다. 기술, MCP 서버, 규칙 파일 간의 경계에서는 올바른 해결책이 새로운 지침이 아닌 새로운 도구를 에이전트에게 제공하는 MCP(Model Context Protocol) 서버일 경우를 포함하여 더 복잡한 사례들을 다룹니다.

검증된 기술 공유하기

일주일간의 실무에서 유용한 것으로 확인된 기술은 기록할 가치가 있습니다. .claude/skills/ 내의 프로젝트 기술은 코드처럼 검토 과정을 거치며 저장소와 함께 전달됩니다. 따라서 저장소를 복제하는 팀원은 별도의 설정 단계 없이 수정 사항을 즉시 적용받을 수 있습니다. 복사 및 붙여넣기 없이 저장소 간에 기술을 이동하는 방법은 별도의 문제이며, 에이전트 기술을 여러 저장소에서 공유하는 방법에서 다룹니다.

이식성에 관한 주의 사항입니다. Claude Code는 긴 frontmatter 필드 목록을 허용하지만, Agent Skills 표준은 name, description, license, compatibility, metadata, allowed-tools 등 단 6개 필드만 허용합니다. 이 외의 필드가 포함된 기술을 claude.ai에 업로드하거나 Skills API용으로 패키징하면, 해당 필드를 무시하는 대신 즉시 오류가 발생합니다.

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

위 6개 필드 내에서 작성하면 동일한 파일이 Claude Code를 비롯해 해당 표준을 읽는 모든 환경에서 로드됩니다. 파일이 로드되는 위치에 따라 수행 가능한 작업이 결정되는데, 이는 Cowork는 Anthropic 샌드박스에서 실행되지만 Claude Code는 사용자 본인의 머신이나 VPS에서 실행되기 때문입니다. 따라서 위에서 언급한 nginx 기술은 팀원의 작업 환경으로 가져갈 가치가 있지만, 서버에 접근할 수 없는 샌드박스 환경에서는 무의미합니다. 다른 모델로 이동해도 기술이 정상 작동하도록 지침을 작성하는 것은 별개의 작업이며, 모든 모델에서 작동하는 기술 작성법에서 다룹니다.

FAQ

SKILL.md 파일은 어느 정도 길이어야 합니까?

500줄 미만으로 유지하십시오. 대부분의 유용한 스킬은 이보다 훨씬 짧습니다. 스킬이 호출되면 본문 내용이 대화 맥락에 포함되어 세션이 끝날 때까지 유지되므로, 모든 줄은 일회성 비용이 아닌 반복적인 비용으로 작용합니다. 긴 참조 자료는 스킬 디렉터리의 별도 파일로 옮기고 SKILL.md에서 한 단계 깊이 링크하십시오. 그러면 에이전트가 필요할 때만 해당 파일을 읽습니다. 번들 스크립트는 읽히는 대신 실행되므로 출력값에 대한 비용만 발생합니다.

스킬이 전혀 트리거되지 않는 이유는 무엇입니까?

모델이 스킬 사용 여부를 결정할 때 컨텍스트에 포함되는 유일한 부분이 설명(description)이므로, 보통 설명이 원인입니다. 설명에는 스킬이 무엇을 하는지뿐만 아니라 언제 사용해야 하는지 명시하고, 사용자가 요청 시 실제로 입력하는 단어가 포함되어 있는지 확인하십시오. 설명이 올바르다면 disable-model-invocation: true을 확인하십시오. 이 설정은 모델로부터 스킬을 완전히 숨깁니다. 또한 paths glob 설정이 현재 작업 중이지 않은 파일로 제한되어 있는지 확인하십시오. 시작 디렉터리 하위의 중첩된 .claude/skills/ 디렉터리에 있는 스킬도 원인이 될 수 있습니다. 이 경우 에이전트가 해당 하위 디렉터리의 파일을 읽거나 편집한 후에만 스킬이 로드됩니다.

스킬로 만들어야 합니까, 아니면 규칙 파일(rules file)에 한 줄로 적어야 합니까?

해당 작업이 얼마나 자주 적용되는지 자문하십시오. 규칙 파일은 모든 세션에서 로드되므로 패키지 관리자나 브랜치 명명 규칙처럼 모든 작업에 공통으로 적용되는 사실을 담아야 합니다. 스킬은 실행될 때만 로드되므로, 일부 작업에서만 중요한 절차를 담기에 적합합니다. 동일한 지침을 두 곳 모두에 작성하지 마십시오. 두 복사본의 내용이 달라지면 에이전트가 무엇을 따랐는지 파악할 수 없게 됩니다.

스킬이 실제로 도움이 되었는지 어떻게 알 수 있습니까?

기준점(baseline)과 비교하십시오. 실제 요청 몇 가지를 수집하여, 스킬을 사용할 수 있는 상태의 새 세션에서 각각 실행한 뒤, /skills 메뉴에서 스킬을 끄고 다시 실행하여 두 답변을 나란히 비교하십시오. 스킬을 작성한 대화에는 이미 사용자의 설명이 포함되어 있어 불완전한 파일도 완전한 것처럼 보일 수 있으므로, 반드시 새 세션에서 테스트해야 합니다. skill-creator 플러그인은 이 비교를 자동으로 수행하여 토큰 비용과 함께 성공률을 보고합니다.

다른 에이전트와 동일한 SKILL.md를 사용할 수 있습니까?

네, Agent Skills 표준에서 정의한 필드인 name, description, license, compatibility, metadata 및 allowed-tools 내에서 유지한다면 가능합니다. Claude Code는 훨씬 더 많은 필드를 허용하며, 다른 도구에서는 실행하지 않는 셸 명령 주입과 같은 본문 기능도 지원합니다. 표준 외의 필드가 포함된 스킬을 업로드하면 허용된 속성을 나열하는 명시적 오류가 발생하므로, 스킬을 Claude Code 전용으로 둘지 범용으로 사용할지 초기에 결정하십시오.