나만의 에이전트 스킬 작성법: 실제 장애 사례 활용하기

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

나만의 에이전트 스킬을 작성하는 가장 좋은 방법은 실제 발생한 장애 사례에서 핵심을 추출하는 것입니다. 코딩 에이전트가 두 번 이상 잘못 수행한 작업을 찾고, 그때마다 직접 입력했던 수정 사항을 기록한 뒤, 에이전트가 스스로 불러올 수 있도록 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에서 링크를 걸어 사용하며, 링크는 1단계 깊이로 유지하십시오. 참조된 파일에서 다시 참조된 파일은 일부만 읽힐 가능성이 있기 때문입니다.
• scripts/: 에이전트가 읽는 대신 실행하는 파일입니다. 출력 결과만 컨텍스트 비용에 포함되므로 300줄짜리 스크립트라도 비용 부담이 적습니다.

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

• 저장소 내의 .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를 안전하게 테스트하고 재로드합니다"는 적절하지만, "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에 저장하며, 각 케이스를 별도의 하위 에이전트에서 실행하므로 모든 실행은 깨끗한 컨텍스트에서 시작됩니다. 이후 스킬을 사용했을 때와 사용하지 않았을 때의 비교 결과를 작성합니다. 이것이 진정한 수치입니다. 즉, 스킬 사용으로 인해 소모되는 토큰과 시간 대비 개선된 통과율을 측정하는 것입니다.

실패 모드: 스킬이 전혀 트리거되지 않음

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

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

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

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

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

실패 유형: 기술(skill)은 규칙 파일에 포함되어야 합니다

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

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

검증된 기술 공유하기

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

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

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

위의 여섯 가지 필드 내에서 작성하면 동일한 파일이 Claude Code를 비롯해 해당 표준을 읽는 모든 환경에서 정상적으로 로드됩니다. 다른 모델에서도 작동하도록 지침을 작성하는 것은 별개의 작업이며, 모든 모델에서 작동하는 기술 작성법에서 자세히 설명합니다.

FAQ

How long should a SKILL.md file be?

Keep it under 500 lines, and expect most useful skills to be far shorter than that. The body enters the conversation when the skill is invoked and stays there for the rest of the session, so every line is a recurring cost rather than a one-time one. Move long reference material into separate files in the skill directory and link them from SKILL.md, one level deep, so the agent reads them only when it needs them. Bundled scripts are executed instead of read, so they cost only their output.

Why does my skill never trigger?

The description is the usual cause, because it is the only part of the skill in context when the model decides. Make sure it says when to use the skill, not only what it does, and that it contains the words you actually type in your requests. If the description looks right, check the frontmatter for disable-model-invocation: true, which hides the skill from the model completely, and for a paths glob that limits it to files you are not touching. A skill in a nested .claude/skills/ directory below your starting directory is another cause: it loads only after the agent reads or edits a file in that subdirectory.

Should this be a skill or a line in my rules file?

Ask how many of your tasks it applies to. A rules file loads in every session, so it should hold facts that are true for every task, such as the package manager or the branch naming convention. A skill loads only when it fires, so it is the right home for a procedure that matters on a small share of tasks. Never write the same instruction in both places, because the two copies drift and you lose the ability to tell which one the agent followed.

How do I know a skill actually helped?

Compare it against a baseline. Collect a few real requests, run each one in a fresh session with the skill available, then run them again with the skill switched off from the /skills menu, and read both answers side by side. A fresh session matters because the conversation where you wrote the skill still contains your explanations, which makes an incomplete file look complete. The skill-creator plugin runs this comparison for you and reports the pass rate next to the token cost.

Can I use the same SKILL.md with a different agent?

Yes, as long as you stay inside the fields the Agent Skills standard defines: name, description, license, compatibility, metadata and allowed-tools. Claude Code accepts many more fields, and it also supports body features such as shell command injection that other tools do not run. Uploading a skill with a field outside the standard fails with an explicit error listing the allowed properties, so decide early whether a skill is meant to stay in Claude Code or travel.