Agent Skills와 SKILL.md: 점진적 공개를 숫자로 검증하다

14장은 이 과정 후반부의 규칙을 정했습니다. 연결, 재시도, 취소는 TypeScript입니다. 그리고 예외 다섯 가지를 선언했습니다. 이것은 그중 하나이며, 이유는 취향이 아닙니다.

skill은 Markdown 파일입니다. 프로그램을 설정하는 파일도 아니고, 프로그램이 컴파일하는 파일도 아닙니다. 모델이 여러분이 입력한 메시지를 읽는 것과 같은 방식으로 읽는 문서입니다. 이 장에 프로그래밍 언어를 붙인다면 형식을 이해하지 못했다는 뜻이고, 바로 그 오해가 skill에 관한 가장 흔한 오해입니다. 아래의 모든 것은 Markdown과 YAML이며, 여기에 작은 shell script 하나가 더해집니다. 그 script는 정확히 코드가 skill 안의 어디에 속하고 어디에 속하지 않는지를 보여주기 위해 존재합니다.

실제 지침 하나를 보겠습니다. 한 회사가 릴리스 노트를 작성하는 방법입니다. 이것은 취향이 아니라 절차입니다. 순서가 있는 단계, 분류 체계, 목소리, 템플릿, 그리고 원자료를 수집하는 script가 있습니다.

대부분의 팀처럼 이것을 전부 시스템 prompt에 넣으면 16장의 산수가 작동합니다. 시스템 prompt는 prefix이고, prefix는 모든 호출에서 비용을 냅니다. 이 장을 위해 작성한 폴더를 대상으로 o200k_base로 측정하면 다음과 같습니다.

whole thing pasted into the system prompt   1,716 x 40  =  68,640 input tokens   $0.1373
as a skill, activated once on turn 12          46 x 40
                                            + 324 (SKILL.md body)
                                            + 665 (two reference files read)
                                                        =   2,829 input tokens   $0.0057
as a skill, never activated at all             46 x 40  =   1,840 input tokens   $0.0037

사용될 때는 24배, 사용되지 않을 때는 37배 더 쌉니다. 요금은 16장의 값입니다. 입력 token 백만 개당 $2.00입니다.

이제 정직한 반론을 말해야 합니다. 이걸 건너뛰는 장은 광고가 될 테니까요. prompt caching은 비용 격차를 대부분 좁힙니다. 시스템 prompt는 안정적이고 맨 앞에 놓이므로 가능한 최고의 캐시 후보입니다. 캐시된 입력 백만 token당 $0.20이면 같은 68,640 token의 비용은 $0.1373이 아니라 $0.0168입니다. 그래도 skill보다 세 배 비싸지만, 더 이상 자릿수가 다른 차이는 아닙니다.

돈은 애초에 가장 강한 논거가 아니었습니다. 핵심은 이것입니다.

Caching은 영구 prefix를 더 싸게 만듭니다. 더 작게 만들지는 않습니다.

40번째 turn에서도 시스템 prompt 버전은 전혀 다른 주제의 대화 중에 릴리스 노트 정책 1,716 token을 window 안에 계속 넣어 둡니다. 그것은 24장이 모델의 attention budget이라고 부른 것을 두고 경쟁합니다. skill 버전은 46 token입니다. 잘못된 것을 cache하면, 여러분은 산만함에 대한 할인을 산 것입니다.

$n$개의 turn, $L_1$를 metadata, $L_2$를 body, $L_3$를 전체 bundle, $R$를 실제로 읽힌 bundled file 집합이라고 두면 공식은 다음과 같습니다.

이 장 전체는 두 번째 항에 $n$을 곱하는 것과, 그것에 1이나 0을 곱하는 것의 차이입니다.

skill은 directory입니다. 명세는 전부 적을 수 있을 만큼 짧습니다.

release-notes/
├── SKILL.md          # required: YAML frontmatter + Markdown instructions
├── scripts/          # optional: executable code
├── references/       # optional: documentation read on demand
├── assets/           # optional: templates, schemas, examples
└── ...               # anything else you like

SKILL.md는 YAML frontmatter로 시작해야 하며, 필수 field는 정확히 두 개입니다. name와 description입니다.¹ 네 개가 더 선택 사항이고, 그 외의 field는 정의되어 있지 않습니다.

다음은 릴리스 노트 skill 전체입니다. body는 30줄이 되지 않습니다.

---
name: release-notes
description: Write the release notes for a tagged version in this company's house style. Use when preparing a release, drafting a changelog entry, or when someone asks for the notes for a version number or a tag.
allowed-tools: Bash(git log:*) Bash(git tag:*) Read
---

# Release notes

## Procedure

1. Run `scripts/collect.sh <previous-tag> <new-tag>`. It prints one line per merged
   pull request: number, title, author and the labels.
2. Drop every line whose labels contain `internal`, `ci` or `chore`.
3. Put each surviving line into exactly one of the four categories in
   [references/categories.md](references/categories.md). A change that seems to fit two
   belongs in the higher one; the order in that file is the order of precedence.
4. Rewrite each line as a sentence in the voice defined in
   [references/voice.md](references/voice.md). The pull request title is a note to
   the team; the release note is a note to a stranger.
5. Check the result against [references/examples.md](references/examples.md).

## The one rule that is not negotiable

Every note says what a person can now do, or what stopped happening to them. If a
sentence can only be understood by someone who has read the diff, it is not finished.

그 body가 무엇인지 읽어 보십시오. 그것은 정책이 아닙니다. 작업 순서가 있는 목차입니다. 정책은 이름으로 가리키지만 포함하지 않는 세 파일에 있습니다. 그리고 1단계는 작업을 script에 넘깁니다. script의 코드는 context window에 전혀 들어가지 않기 때문입니다. 들어가는 것은 오직 출력뿐입니다.²

로드 모델에는 이름과 세 단계가 있습니다. 명세는 token budget을 붙여 그것들을 설명합니다.¹

1. Metadata, 약 100 token: name와 description. 설치된 모든 skill에 대해 시작 시 로드됩니다.
2. Instructions, 권장 5,000 token 미만: SKILL.md body. skill이 활성화될 때 로드됩니다.
3. Resources, 필요할 때: bundled file. 무언가가 요구할 때만 로드됩니다.

참조 문서는 같은 표에 네 번째 열 — 언제 로드되는가, token 비용, content — 을 붙입니다. 중요한 행은 세 번째입니다. 접근 전까지는 없음입니다.³ 이 장 전체를 요약하는 문장도 거기에 있습니다.

Files don't consume context until accessed, so Skills can include comprehensive API documentation, large datasets, or extensive examples. There's no context penalty for bundled content that isn't used.³

이 장 맨 위의 측정 표는 이 글을 위해 작성되지 않은 다섯 skill을 대상으로 그 주장을 확인한 것입니다. 두 행은 서로 맞대어 읽을 가치가 있습니다.

next-best-practices는 966-token body를 가지고 있고, 그 body는 19,374 token을 담은 19개 파일로 link합니다. hydration error를 고치라고 요청하면 agent는 body와 hydration-error.md만 읽습니다. 20,340개 중 1,409 token, 14배 차이이며, 나머지 18개 파일은 열리지도 않습니다.

next-cache-components는 2,334-token body를 가지고 있으며 bundled file이 전혀 없습니다. 이것은 유효한 skill이고 잘 작성된 skill이지만, 공개할 level 3이 없습니다. 이것이 이 기법의 정직한 한계입니다. progressive disclosure는 미룰 것이 있을 때만 절약입니다. 지식이 분해되지 않는 skill은 활성화될 때 body 전체 비용을 내며, 남은 lever는 그것을 활성화하지 않는 것뿐입니다.

Level 1은 한 문장으로 내리는 routing 결정입니다. skill의 다른 어떤 것도 그것이 열릴지에 영향을 주지 않습니다. body의 품질도, 예시도, script도 아닙니다. 따라서 description은 documentation이 아닙니다. 그것은 query surface이며, 틀릴 수 있습니다.

명세는 좋은 예와 나쁜 예의 형태로 그 사실을 말합니다. 나쁜 예는 네 단어입니다. description: Helps with PDFs.¹ 이것은 받아들이기보다 측정할 가치가 있습니다.

여섯 개의 skill, 각각 무엇을 하는지와 언제 써야 하는지를 말하는 그럴듯한 description을 가집니다. 24개 요청, skill당 4개, 사람이 말할 법하게 표현하고 skill 이름은 절대 말하지 않습니다. 모델은 시스템 prompt 안의 여섯 줄을 보고 이름 하나 또는 NONE로 답해야 합니다. Greedy decoding이므로 재현됩니다. 그런 다음 같은 여섯 skill과 같은 24개 요청을 두고, description을 bare subject로 줄였습니다.

rich   - sql-review: Review a SQL migration for locks, missing indexes and unsafe
         defaults before it runs on the production database. Use when someone adds
         or changes a migration, an index, or a table column.
thin   - sql-review: Helps with SQL.

rich   295 tokens of level 1 for six skills   18/24 correct = 75.0 %  [55.1, 88.0]
thin    81 tokens of level 1 for six skills   10/24 correct = 41.7 %  [24.5, 61.2]

paired: rich only 9, thin only 1, two-sided sign test p = 0.0215
answered NONE: rich 1 of 24, thin 9 of 24

먼저 interval을 읽으십시오. 4장이 주장했고 29장이 다시 주장할 것처럼, 그것들은 겹칩니다. 24개 case만으로 두 system의 aggregate 순위를 매길 수는 없습니다. 결론을 내리는 것은 paired comparison이며, 이것은 15장의 도구입니다. 두 arm이 불일치한 10개 case 중 9개는 풍부한 description 쪽이 이겼고, 1개는 얇은 description 쪽이 이겼습니다. 이는 통상 threshold에서 성립합니다.

이제 실제 발견인 마지막 줄을 읽어 보십시오. 얇은 description에서 모델은 24개 요청 중 9개에 대해 NONE라고 답했습니다. 잘못된 skill이 아니라, skill 없음입니다. 그중 네 개를 그대로 적으면 다음과 같습니다.

"Check this migration before I run it against production."     -> release-notes
"Will this CREATE INDEX lock writes?"                          -> NONE
"Is this ALTER TABLE safe to deploy at peak traffic?"          -> NONE
"Is 'seamless and powerful' allowed in the app store listing?" -> next-best-practices

완벽한 sql-review skill이 설치되어 있었고, body와 예시와 checklist가 있었지만, 그 skill을 위해 작성된 세 질문에서 세 번 연속으로 한 번도 열리지 않았습니다. level 1에 도달하지 못한 skill에게 level 2와 3은 무의미합니다.

이를 고치는 비용은 214 token입니다. 여섯 skill에 걸친 295와 81의 차이입니다. 이것은 반대쪽에서 도착한 18장의 발견입니다. 거기서는 도구의 description만 바꾸었더니 date formatting이 24개 중 2개 정답에서 24개 중 24개 정답으로 바뀌었습니다. 여기서는 skill의 description만 바꾸자 activation이 24개 중 10개에서 18개로 바뀝니다. 두 경우 모두 system에서 가장 싼 수정은 한 문장이고, 두 경우 모두 그 문장은 subject만이 아니라 trigger를 이름 붙여야 합니다. 그 물건이 무엇인지가 아니라, 그것이 적용될 때 사용자가 방금 무엇이라고 말했을지를 말해야 합니다.

이 장은 자신의 기준에 따라 caveat 하나를 빚지고 있습니다. 이것은 5억 parameter 모델이고, frontier model은 75%보다 훨씬 더 잘 routing합니다. 크기가 아니라 메커니즘을 읽으십시오. routing signal은 어떤 모델이 읽든 한 문장 길이이며, 어떤 모델도 그 문장에 넣지 않은 정보를 기준으로 선택할 수 없습니다.

두 번째 실패는 첫 번째와 반대입니다. skill은 발견되고, level은 올바르게 나뉘지만, agent가 결국 전부 읽어 버립니다.

vercel-react-best-practices는 정말 잘 만들어진 skill입니다. 1,670-token body는 여덟 category의 priority table과 70개 rule file을 한 줄씩 이름 붙인 quick reference입니다. rule들은 그 옆 disk에 있습니다. 70개 파일, 가장 작은 것은 132 token, median은 319, 가장 큰 것은 1,052입니다. barrel import에 대해 질문 하나를 하면 정직한 비용은 body와 파일 하나입니다. 53,670 token짜리 bundle에 비해 2,400 token 미만입니다.

그런데 body의 마지막 줄은 이렇게 말합니다.

## Full Compiled Document

For the complete guide with all rules expanded: `AGENTS.md`

AGENTS.md는 26,362 token입니다. 70개 rule file을 이어 붙인 것입니다. 그 합계가 25,784이고, 차이는 그 사이의 heading입니다. 그러므로 이 skill은 agent에게 median rule 하나를 319 token에 읽는 선택지와, 같은 content 전체를 여든세 배 가격에 읽는 선택지를 동시에 제공합니다. 그리고 그 선택지를 비용도 조건도 없는 한 문장으로 제공합니다.

그것은 bug가 아니고 file이 틀린 것도 아닙니다. compiled document는 사람에게 진짜로 유용하고, codebase 전체를 audit하라는 요청을 받은 agent에게도 유용합니다. 그것은 level-2 invitation을 가진 level-3 file이며, 교훈은 이 skill 하나를 넘어 일반화됩니다. SKILL.md에서 빠져나가는 모든 path는 비용이 얼마이고 언제 그만한 가치가 있는지 말해야 합니다. 모델은 어떤 filename이 그 위의 filename보다 여든세 배 더 비싼지 알 방법이 없기 때문입니다.

같은 folder에는 staleness에 관한 더 작은 교훈도 있습니다. body는 “70 rules across 8 categories”라고 말하고 70개를 나열합니다. rules/ directory에는 72개 파일이 있으며, 그중 두 개는 scaffolding입니다(_template.md와 _sections.md). 그리고 sidecar metadata.json는 “40+ rules”라고 말합니다. 한 folder 안에 같은 집합의 count가 세 개 있고, 하나는 맞고, 하나는 산수이며, 하나는 이전 version에서 남은 것입니다. skill은 문서이고, 문서는 옆의 code에서 멀어져 버린 code comment와 정확히 같은 방식으로 썩습니다. 차이는 이것이 눈썹 하나 올리지 않는 기계에게 읽힌다는 점뿐입니다.

open specification은 여섯 개 frontmatter field를 정의합니다. reference implementation인 Claude Code는 스무 개를 받습니다.² 다섯 group은 이름으로 알아 둘 가치가 있습니다. format이 단순한 문서이기를 멈추는 지점이기 때문입니다.

Arguments(arguments, argument-hint)는 사람이 값을 넘겨 body에 치환되게 하며, 이것이 skill을 slash command로 쓸 수 있게 만듭니다. Scoping(paths)은 glob과 일치하는 file로 activation을 제한합니다. 그리고 dynamic context injection은 mental model을 바꾸는 항목입니다. !`git diff HEAD` 형식의 줄은 body가 전송되기 전에 실행되고, 그 출력이 text에 치환됩니다. 문서는 template이며, 그 일부는 읽히는 시점에 계산됩니다.

이제 함정입니다. 같은 documentation에 명시되어 있습니다. Claude Code 밖 — web product, Skills API, packaging — 에서는 명세된 여섯 field만 허용되며, 다른 field는 upload 시 hard error입니다.² 그러므로 한 제품에서 완벽히 작동하는 skill이 같은 vendor의 다른 제품에는 설치되지 않습니다. 그리고 prose를 읽어 test할 수 있는 어떤 지점이 아니라 frontmatter에서 실패합니다. skill을 portable하게 만들 생각이라면 여섯 field가 전체 budget입니다. 그렇지 않다면 정확히 이를 위해 존재하는 compatibility에 그렇게 적으십시오.

네 가지는 끊임없이 서로 혼동됩니다. 그리고 그 혼동은 어휘 집착이 아닙니다. 잘못 고르면 매 turn마다 돈을 내거나, 있다고 믿었던 보장을 잃습니다.

굵게 표시한 두 행이 전체 구분입니다. skill은 읽히고, 도구는 호출됩니다. skill은 context window에 도착해 그 안의 다른 모든 것과 attention을 두고 경쟁하는 prose입니다. 모델은 그것을 따를 수도, 잘못 읽을 수도, 무시할 수도 있으며, system의 어떤 것도 알아차리지 못합니다. 도구는 모델의 손을 완전히 떠나는 호출입니다. 여러분의 코드가 arguments를 받고, validate하고, permission을 확인하고, 결정합니다. 18장은 이를 모델이 제안하고 여러분의 코드가 처분한다고 표현했습니다. 그 분리가 바로 skill에는 없습니다.

그러므로 실제 여섯 case는 이렇게 정리됩니다.

역사는 짧고, 이례적으로 날짜가 잘 찍혀 있으며, 거의 아무도 말하지 않는 부분입니다.

Agent Skills는 2025년 10월 16일 한 vendor의 기능으로 공개되었습니다. 그 발표는 이를 “agents can discover and load dynamically to perform better at specific tasks”인 “organized folders of instructions, scripts, and resources”라고 정의했고, 세 level을 기억할 만한 비유로 설명했습니다. “잘 정리된 manual처럼, 목차로 시작해 특정 chapter로 들어가고 마지막으로 상세 appendix에 도달한다”는 비유입니다.⁴

2025년 12월 18일 같은 page는 format을 open standard로 발표하도록 업데이트되었습니다. 자체 specification은 agentskills.io에 있고, governance는 contribution에 열려 있으며, reference validator가 있습니다.³ 2026년 9월 7일에 읽은 standard의 client showcase에는 editor, terminal, cloud platform, mobile runtime 등 46개 product가 나열되어 있었습니다. Anthropic, OpenAI, Google, Mistral의 first-party coding agent도 포함되며, 각각 자체 setup documentation으로 link합니다.¹

MCP와의 convergence는 공개적으로 진행되고 있으며, 확인할 수 있는 숫자가 있습니다.

흥미로운 부분은 proposal이 아니라 closure입니다. SEP-2076은 tools, resources, prompts 옆의 네 번째 primitive를 요구했습니다. 거기서 생긴 working group은 답이 아니오라고 결정했습니다. skill은 이미 존재하는 resources primitive 위에 opt-in extension으로 올라탑니다.⁵ 26장은 protocol 자체 changelog에서 같은 본능을 측정했습니다. sampling, roots, logging은 유지되지 않고 deprecated되었습니다. 자신이 작성한 proposal을 제거하는 standards body는 잘 행동하고 있는 것입니다. 이 이야기를 숫자와 함께 해야 하는 이유는, 여러분이 다른 곳에서 읽을 요약들이 아직도 skill을 MCP primitive라고 설명하기 때문입니다.

이제 여러분은 SKILL.md를 작성하고, 비용을 스스로 회수하는 세 level로 나누고, 다른 사람이 만든 skill의 frontmatter를 읽고 어떤 field가 다른 곳에 upload될 때 살아남지 못할지 알 수 있습니다. 또한 이 장 전체가 중심에 둔 질문 — 시스템 prompt, skill, 도구, server — 에 습관이 아니라 이유로 답할 수 있습니다.

하지만 여러분 것은 작동하는지 알 수 없습니다.

이 장에서 중요했던 모든 claim은 measurement였고, 가장 중요했던 것은 accuracy였습니다. 24개 중 18개와 24개 중 10개, 각각의 interval과 둘 사이의 paired test가 있었습니다. 겹치는 두 aggregate는 아무것도 결정하지 못하기 때문입니다. 그 instrument는 빌려온 것입니다. skill의 description은 routing key이고, body는 모델이 따를 수도 따르지 않을 수도 있는 procedure입니다. 이 둘은 모두 같은 것을 여러 번 실행하고 돌아온 결과를 scoring해야만 알 수 있는 속성입니다. 그것은 golden set, 실행 전에 작성한 grader, 그리고 적어도 한 번이 아니라 매번 작동했는지를 묻는 metric입니다.

29장이 그것이며, 이 장의 방법이 의존하는 숫자로 시작합니다. 10번 중 7번 성공하는 agent는 70%처럼 보이지만, 그것의 pass^10 — 열 번 모두 성공할 확률 — 은 0입니다. 또한 같은 200개 transcript에 세 grader를 측정해 단 하나의 token도 다시 생성하지 않고 0%, 13%, 26%를 얻습니다. 방금 description에 쓴 문장을 믿기 전에, 그것이 대체한 문장보다 더 나쁘다는 것을 말해 줄 수 있는 instrument가 필요합니다.

이 장의 모든 token count는 2026년 9월 7일에 tiktoken 0.14.0과 o200k_base encoding으로 local에서 생성했습니다. 이 장 첫머리에 나열한 다섯 third-party skill과, 이 장을 위해 작성한 release-notes skill을 대상으로 했으며, 그 전체 text의 일부는 위에 재현되어 있습니다. Level 1은 host가 시스템 prompt로 render하는 단일 line - name: description로 측정했습니다. level 2는 frontmatter 이후의 SKILL.md body입니다. level 3은 folder 안의 다른 모든 file입니다. 비용은 gpt-5.6-terra에 대해 16장이 측정한 요금, 입력 token 백만 개당 $2.00 및 cached input token 백만 개당 $0.20을 이 count에 적용했습니다. 이것은 측정된 token에 대한 산수이지 live bill의 관찰이 아닙니다. 이 장을 쓰기 위해 유료 API는 호출하지 않았습니다.

activation experiment는 consumer GPU 하나에서 half precision으로 Qwen/Qwen2.5-0.5B-Instruct를 실행했고, greedy decoding을 사용했습니다. 여섯 skill에 대한 24개 요청을 두 번 실행했습니다. 한 번은 skill이 무엇을 하고 언제 적용되는지 명시한 description으로, 한 번은 specification 자체의 “poor example” 스타일처럼 bare subject로 줄인 description으로 실행했습니다. Interval은 95% Wilson입니다. paired comparison은 10개 discordant case에 대한 two-sided exact sign test입니다. Wilson interval은 4장의 것, exact paired sign test는 15장의 것이며 둘 다 변경 없이 재사용했습니다. magnitude는 아주 작은 모델의 속성으로, method는 이전 가능한 것으로 읽으십시오.

여기서 측정한 다섯 skill은 이 장을 위해 작성된 것이 아닌 third-party package입니다. vercel-labs/next-skills의 next-best-practices와 next-cache-components, 그리고 vercel-labs/agent-skills의 vercel-composition-patterns, vercel-react-best-practices, vercel-react-native-skills입니다. 내부 count — 70개 rule file, 26,362 token의 AGENTS.md, 2026년 1월 날짜이며 “40+ rules”라고 주장하는 metadata.json — 는 2026년 9월 7일 disk의 file에서 읽은 것이고, 그 published version의 속성이지 저자에 대한 비판이 아닙니다. 그 모든 것은 count보다 자주 편집되는 documentation tree라면 어디에나 나타나는 drift입니다.