Agent Skills 명세의 필드는 여섯 개, 호출·권한 설정은 도구마다 다릅니다

핵심 요약

먼저 알아 둘 용어

• 스킬은 SKILL.md와 선택적인 스크립트·참고 문서·템플릿을 담은 폴더입니다. 에이전트는 필요할 때 이 폴더의 내용을 읽어 절차를 따릅니다.
• 프런트매터는 SKILL.md 맨 위 --- 사이에 쓰는 YAML 설정 영역입니다. 스킬 이름과 설명, 호출 방식 같은 설정이 여기에 들어갑니다.
• 단계적 로딩(progressive disclosure)은 처음에는 이름과 설명만 컨텍스트에 올리고, 스킬을 쓰기로 했을 때 본문을, 본문이 가리킬 때 나머지 파일을 읽는 방식입니다. 컨텍스트는 모델이 한 번에 받는 입력 전체를 말합니다.
• 자동 호출은 에이전트가 요청 내용과 스킬 설명을 비교해 스스로 스킬을 고르는 것이고, 명시적 호출은 사용자가 /skill-name이나 $skill-name처럼 직접 부르는 것입니다. Codex 문서는 이 둘을 implicit·explicit invocation이라고 부릅니다.
• 사전 승인은 스킬이 쓸 도구를 미리 허용해, 사용자에게 매번 확인을 묻지 않게 하는 설정입니다. 명세의 allowed-tools 필드가 이것입니다.

명세가 정한 것 — 폴더 하나와 필드 여섯 개

agentskills.io의 명세에 따르면 스킬은 최소한 SKILL.md 하나를 가진 디렉터리입니다. scripts/(실행 코드), references/(참고 문서), assets/(템플릿·이미지·데이터)는 선택이며, 명세는 이 세 폴더를 "권장 관례"로 적고 그 밖의 파일과 폴더도 허용합니다. [1]

my-skill/
├── SKILL.md          # 필수: 프런트매터 + 지시문
├── scripts/          # 선택: 실행 코드
├── references/       # 선택: 참고 문서
└── assets/           # 선택: 템플릿·이미지·데이터

이 글의 2026-06-16 초판은 이 구조에 agents/ 폴더를 함께 적었습니다. 명세가 추가 폴더를 허용하므로 틀린 구조는 아니지만, 명세가 정한 폴더는 아니며 그 안의 agents/openai.yaml은 Codex가 읽는 설정 파일입니다(아래 도구별 비교 참조). [6]

본문 형식에는 제한이 없습니다. 명세는 단계별 지시, 입력과 출력의 예, 흔한 예외 상황을 본문에 넣으라고 권하고, 단계적 로딩의 기준으로 세 단계를 제시합니다. 에이전트는 시작할 때 모든 스킬의 이름과 설명을 읽으며, 이 정보는 스킬 하나당 약 100토큰입니다. 본문은 스킬을 쓰기로 했을 때 통째로 읽으며 5,000토큰 미만을 권장하고, 나머지 파일은 필요할 때만 읽습니다. 그래서 SKILL.md는 500줄 아래로 두고 긴 자료는 별도 파일로 빼며, 파일 참조는 SKILL.md에서 한 단계 깊이까지만 두라고 권합니다. 형식 검사는 명세가 함께 내놓은 skills-ref validate ./my-skill로 합니다. [1]

---
name: summarize-changes
description: Summarizes uncommitted git changes and flags risky edits. Use when the user asks what changed or wants a commit message.
---

## Steps
1. Read the current git diff.
2. Summarize the changes in three bullets or fewer.
3. List risks: missing tests, error handling, hardcoded values.
4. Suggest one commit message.

명세의 두 필수 필드만 쓴 예입니다. 디렉터리 이름도 summarize-changes여야 합니다.

도구마다 다른 것 — 경로, 자동 호출 차단, 사전 승인

세 도구의 문서는 모두 Agent Skills 명세를 따른다고 적습니다. 그러나 스킬을 찾는 경로와 명세 밖의 설정은 다릅니다. 아래 표는 2026-10-06에 확인한 각 공식 문서의 내용이며, 세 도구에 같은 스킬을 직접 설치해 확인한 결과는 아닙니다. [2] [6] [7]

표에서 실무자가 바로 확인해야 할 차이는 세 가지입니다.

• Claude Code와 Codex는 저장소 안 경로가 겹치지 않습니다. Claude Code는 .claude/skills/를, Codex는 .agents/skills/를 읽습니다. 두 문서 모두 심볼릭 링크로 연결한 스킬 폴더를 따라간다고 적고 있으므로, 한쪽에 원본을 두고 다른 경로에서 링크하면 같은 파일을 쓸 수 있습니다. VS Code는 세 경로를 모두 읽습니다.
• 자동 호출을 막는 설정 위치가 다릅니다. 배포·메시지 전송처럼 부작용이 있는 스킬에 Claude Code와 VS Code는 SKILL.md의 disable-model-invocation을, Codex는 별도 파일 agents/openai.yaml을 씁니다. 한쪽 설정만 해 두면 다른 도구에서는 에이전트가 그 스킬을 스스로 고를 수 있습니다.
• name을 생략하거나 디렉터리 이름과 다르게 쓴 스킬은 Claude Code에서만 확실히 동작합니다. Claude Code는 name이 없으면 디렉터리 이름을 쓰지만, Codex와 VS Code 문서는 name을 필수로 두고, VS Code 문서는 디렉터리 이름과 다르면 스킬을 불러오지 않는다고 적습니다.

Anthropic 제품 안에서도 다릅니다

Claude Code 문서는 명세에 없는 필드(disable-model-invocation, context, argument-hint 등)를 쓴 스킬을 claude.ai에 올리거나 Skills API로 업로드하면 무시되지 않고 오류로 거부된다고 적습니다. 이 세 필드는 VS Code 문서에도 나오는 필드이지만, 이 업로드 경로에서 허용되는 필드는 명세의 여섯 개뿐입니다. 또 !`명령` 형태로 셸 명령의 출력을 본문에 넣는 Claude Code 기능도 claude.ai 대화와 API에서는 동작하지 않습니다. [2] 실행 환경도 다릅니다. [4]

같은 스킬이라도 Claude Code에서는 외부 API를 부를 수 있고 Claude API에서는 부를 수 없습니다. 스크립트가 네트워크나 패키지 설치에 의존하면 compatibility 필드에 적어 두는 것이 명세의 용도에 맞습니다. [1]

효과는 사람이 다듬은 절차형 스킬에서 나왔습니다

스킬이 실제로 결과를 바꾸는지는 이 글이 확인한 자료 중 SkillsBench가 가장 넓게 측정했습니다. 8개 분야 87개 과제마다 사람이 다듬은 스킬과 결과를 자동으로 채점하는 검증기를 붙이고, 같은 과제를 스킬 없이와 스킬과 함께 풀게 해 18개 모델·실행 환경 조합의 통과율을 비교했습니다. 실행 환경에는 Claude Code, Codex CLI, Gemini CLI, OpenHands가 들어 있습니다. [9]

마지막 줄이 도입할 때 가장 중요합니다. Claude Code + Opus 4.7, Codex + GPT-5.5, Gemini CLI + Gemini 3.1 Pro 세 조합에서, 에이전트가 Anthropic의 스킬 생성 도구인 skill-creator로 스킬을 먼저 만든 뒤 그 스킬만으로 과제를 풀게 하자 통과율이 스킬이 없을 때보다 8.1~11.5%p 낮았습니다. 같은 조합에서 사람이 다듬은 스킬은 18.2~24.8%p를 올렸습니다. 저자들은 원인으로 만든 스킬을 풀이 단계에서 찾지 못한 경우, 스킬을 만드는 작업이 풀이 시간을 잡아먹은 경우, 틀린 내용을 확신 있게 적은 경우를 들었습니다. [9] 즉 이 결과는 "스킬을 자동으로 만들어 두면 된다"는 주장을 뒷받침하지 않습니다. 길이로 보면 짧은 스킬과 보통 길이 스킬이 비슷하게 효과를 냈고, 포괄적인 문서형 스킬은 효과가 거의 없었습니다.

스킬이 오히려 해가 된 과제도 87개 중 13개였습니다. 저자들이 실행 기록을 대조해 찾은 공통점은 적용 범위나 가벼운 대안 없이 "정답 절차" 하나만 처방한 스킬이었습니다. 과하게 무거운 절차를 시키거나, 모델이 원래 잘하던 방법을 밀어내거나, 에이전트가 디버깅할 수 없는 도구를 가리키는 경우입니다. [9]

공식 작성 지침도 같은 방향입니다. Anthropic의 작성 지침은 스킬 없이 대표 과제를 먼저 실행해 실패를 기록하고, 그 실패를 확인하는 평가 시나리오 세 개를 만든 뒤 그것을 통과할 만큼만 지시문을 쓰라고 권합니다. [5] Claude Code 문서는 스킬이 호출되는지와 결과가 기대대로인지를 따로 확인하라고 하며, 새 세션에서 같은 프롬프트를 스킬을 켜고 끈 채로 비교하는 방법을 안내합니다. [2] 스킬을 서브에이전트로 실행하는 context: fork가 언제 이득인지는 스킬을 서브에이전트로 실행하면에서 따로 다뤘습니다.

설명과 본문을 쓰는 기준

• 설명 앞부분에 핵심 용도와 호출 조건을 둡니다. Claude Code와 Codex 문서가 같은 말을 합니다. 스킬이 많으면 목록 한도를 넘어 설명이 잘리고, 잘린 설명으로는 에이전트가 요청과 스킬을 맞추지 못합니다. [2] [6]
• 설명은 무엇을 하는지와 언제 쓰는지를 함께 씁니다. 명세와 Anthropic 문서가 모두 요구하며, Anthropic 작성 지침은 설명이 시스템 프롬프트에 들어가므로 3인칭으로 쓰라고 적습니다. [1] [5]
• 끝까지 지켜야 할 지시는 본문 앞쪽에 두고, 작업 전체에 적용된다는 점이 드러나게 씁니다. Claude Code는 호출된 스킬 본문을 대화에 한 번 넣고 다시 읽지 않습니다. 대화가 요약될 때는 스킬마다 앞 5,000토큰만, 전체 25,000토큰 안에서 최근 호출한 스킬부터 다시 붙입니다. [2]
• 매번 반드시 지켜야 하는 규칙은 스킬이 아니라, 정해진 시점마다 실행되는 명령인 훅으로 둡니다. Claude Code 문서는 훅이 모델이 스킬을 따르는지와 상관없이 동작한다고 안내합니다. [2]

외부 스킬은 설치하는 소프트웨어처럼 검토합니다

Anthropic의 Agent Skills 문서는 직접 만든 스킬이나 Anthropic에서 받은 스킬만 쓰라고 권하고, 출처를 모르는 스킬은 SKILL.md·스크립트·이미지 등 함께 들어 있는 모든 파일을 읽고 검토한 뒤 쓰라고 적습니다. 외부 URL에서 내용을 가져오는 스킬은 그 내용에 악성 지시가 들어 있을 수 있고, 믿을 만한 스킬도 외부 의존성이 바뀌면 오염될 수 있다는 점도 함께 적었습니다. [4]

Claude Code에서 스킬이 실행 권한을 얻는 두 경로

출처: Claude Code Skills 문서와 설정 문서, 2026-10-06 확인. [2] [3]

그래서 Claude Code 문서는 저장소에 들어 있는 스킬의 allowed-tools를 그 저장소에서 Claude Code를 실행하기 전에 읽으라고 권합니다. [2] 권한 규칙으로 스킬 자체를 막을 수도 있습니다. Skill을 거부 목록에 넣으면 모든 스킬이, Skill(deploy *)처럼 쓰면 특정 스킬이 막힙니다. 이 동작이 최근 버전에서 어떻게 바뀌었는지는 Claude Code 플러그인을 팀에 배포하기 전에에, 공식 마켓플레이스에서 allowed-tools로 Bash를 사전 승인하는 플러그인이 몇 개인지는 공식 마켓플레이스 플러그인 315개 전수 조사에 정리했습니다.

공개 마켓의 스킬 3만여 개를 검사한 연구

Liu 외의 연구는 2025년 12월 두 공개 마켓(skills.rest, skillsmp.com)에서 스킬 42,447개를 모은 뒤, 중복된 스킬과 내용이 거의 없는 스킬을 걸러 내고 남은 31,132개를 정적 분석과 대규모 언어 모델(LLM) 분류기로 검사했습니다. [10]

저자들은 26.1%를 "확정된 악성 스킬"이 아니라 "검토가 필요한 패턴"으로 읽으라고 직접 적었습니다. 탐지기의 정밀도는 86.7%, 재현율은 82.5%입니다. 수집 시점에 저장소가 이미 삭제돼 있던 17.3%는 분석에서 빠졌고, 이 중에 악성 스킬이 더 많았을 수 있어 실제 비율은 더 높을 수 있다고도 적었습니다. [10] 스크립트 유무에 따른 차이는 이 표본에서 나타난 상관이며, 저자들이 원인을 밝힌 것은 아닙니다.

설명 문장 하나가 선택을 바꿨습니다

Saha 외의 연구는 SKILL.md만 바꾸는 공격을 실험했습니다. 공개 레지스트리 ClawHub의 스킬 100개마다 기능은 같고 설명 끝에 문장 하나만 덧붙인 변형을 만들어 원본과 나란히 제시했더니, GPT-4.1-mini·GPT-5·Gemma-4-31B·Qwen3-235B 네 모델이 평균 77.6%의 시행에서 변형을 골랐습니다. 무작위로 고르면 50%입니다. 덧붙인 문장은 과장 광고, 단정적인 권유, 보안·신뢰 주장, 활발히 관리된다는 주장 네 가지였습니다. [11] 이 실험은 두 후보 중 하나를 고르게 한 설정이고 Claude Code나 Codex의 실제 스킬 선택 동작을 측정한 것은 아니지만, 저자들의 결론대로 SKILL.md의 설명은 에이전트의 행동을 바꾸는 입력이므로 스크립트와 함께 검토 대상입니다.

체크리스트

1. 대화에 반복해서 붙여 넣는 지시부터 스킬로 옮기세요. Claude Code 문서는 같은 지시·체크리스트·다단계 절차를 계속 붙여 넣을 때, 또는 CLAUDE.md의 한 부분이 사실이 아니라 절차가 됐을 때를 스킬을 만들 시점으로 듭니다.
2. 스킬 없이 대표 과제를 먼저 실행해 실패를 기록하세요. 그 실패 사례를 해결할 만큼만 지시문을 쓰고, 새 세션에서 스킬을 켰을 때와 껐을 때의 결과를 비교합니다.
3. 프런트매터는 명세의 여섯 필드로 시작하고 name을 디렉터리 이름과 같게 두세요. 그래야 VS Code에서 불러오고 claude.ai·Skills API 업로드에서 거부되지 않습니다. 명세 밖 필드는 그 필드를 읽는 도구에서만 동작한다고 보고, claude.ai·Skills API로 올릴 사본에서는 뺍니다.
4. 설명 앞부분에 핵심 용도와 호출 조건을 쓰세요. 목록 한도를 넘으면 설명이 잘립니다.
5. 부작용이 있는 스킬은 쓰는 도구마다 자동 호출을 막으세요. Claude Code·VS Code는 disable-model-invocation: true, Codex는 agents/openai.yaml의 allow_implicit_invocation: false입니다.
6. 남의 저장소에서 Claude Code를 실행하기 전에 .claude/skills/의 allowed-tools와 !`명령`을 읽으세요. 조직이라면 allowManagedPermissionRulesOnly와 disableSkillShellExecution을 관리 설정에서 검토합니다.
7. 외부 스킬은 모든 파일을 읽고 검토한 뒤 도입하세요. 스크립트의 네트워크 호출과 파일 접근, 외부 URL에서 받아 오는 내용, 설명에 붙은 과장된 신뢰 문구를 봅니다. 최근에 갱신됐다는 사실은 안전의 근거가 아닙니다.
8. 매번 반드시 지켜야 하는 규칙은 훅으로 옮기세요. 스킬 지시는 대화가 길어지거나 요약되면 약해질 수 있습니다.

아직 결론이 아닌 것

• 이 글은 2026-06-16에 낸 초기 노트를 2026-10-06에 현재 기준으로 다시 쓴 것입니다. 초판의 문장과 표는 그대로 두지 않고 모든 주장을 원문과 다시 대조했습니다. 초판에 있던 마켓플레이스 설치 순위 상위 10개와 그 차트는 뺐습니다. 출처가 마켓플레이스가 자기 스킬을 소개하는 2차 글이었고, 2026-10-06에 다시 열어 보니 초판이 옮긴 설치 수가 페이지에 없었습니다. 카테고리별 우선순위, 단계별 도입 기간, 업종별 시나리오, 추천 스킬 목록도 근거 없이 초판이 정한 값이어서 뺐습니다. 초판이 지원 도구로 적은 Cursor는 이번에 확인하지 않아 다루지 않았습니다.
• 직접 측정은 하지 않았습니다. 도구별 비교는 공식 문서의 서술이며, 같은 스킬을 세 도구에 설치해 동작을 확인하지 않았습니다. Codex·VS Code 문서에 allowed-tools 언급이 없다는 것은 "문서에 없다"는 뜻이지 "동작하지 않는다"는 확인이 아닙니다.
• Anthropic 문서끼리 어긋나는 곳이 있습니다. Agent Skills 개요 문서는 Claude Code 스킬이 claude.ai·API와 분리돼 있다고 적지만, Claude Code 문서는 claude.ai 계정으로 로그인한 터미널 세션에 계정의 스킬을 내려받아 쓴다고 적습니다. 이 글은 두 서술을 그대로 옮겼고 어느 쪽이 현재 동작인지는 확인하지 않았습니다.
• SkillsBench는 터미널·컨테이너 과제의 결과입니다. 저자들은 GUI 에이전트나 매우 긴 작업에 그대로 옮겨지지 않을 수 있고, 스킬이 컨텍스트를 늘린 것만으로 생긴 효과가 섞였을 수 있다고 적었습니다. 직접 만든 스킬의 결과에도 스킬을 찾지 못한 경우와 만들기·풀기 단계의 간섭이 섞여 있다고 밝혔습니다.
• 26.1%는 탐지기가 표시한 비율입니다. 부주의와 악의를 함께 세었고, 2025년 12월 두 마켓의 스냅숏이며, 기업 내부 배포나 이후 생태계를 대표하지 않는다고 저자들이 적었습니다.
• 설명 조작 실험은 두 후보 중 하나를 고르는 설정입니다. ClawHub 스킬 100개와 네 모델로 측정했고, 실제 에이전트의 스킬 선택 방식이나 다른 모델에서는 결과가 다를 수 있다고 저자들이 적었습니다.
• 세 논문 모두 arXiv 프리프린트입니다. 동료 심사를 거쳤는지는 확인하지 않았습니다.
• 제품 문서와 버전 번호는 빠르게 바뀝니다. 경로·필드·한도·버전은 모두 2026-10-06 확인한 값입니다.

참고자료

모두 2026-10-06에 확인했습니다. 제품 문서는 Markdown 원본(URL 끝에 .md)으로 받아 대조했고, 논문 세 편은 arXiv의 LaTeX 원본에서 값과 한계 절을 확인했습니다. 제품 문서는 개발사가 자기 제품의 동작을 설명한 것이며 독립 검증이 아닙니다.

2026-06-16 초기 노트를 2026-10-06에 현재 기준으로 다시 썼습니다. 제목과 구성을 바꾸고, 원문으로 다시 확인할 수 없는 마켓플레이스 설치 순위와 초판이 근거 없이 매긴 우선순위·기간표를 뺐으며, 도구별 차이와 논문 세 편의 결과를 더했습니다. 2026-09-07 개정에서 코딩 에이전트 비교 글(당시 제목 「2026 AI 코딩 에이전트 지형도」)로부터 옮겨 온 내용 가운데 공개와 오픈 표준 시점은 원문으로 확인해 남겼고, 스킬의 두 가지 역할 구분과 설치 분포는 이번 기준에 맞는 근거가 없어 뺐습니다.