Anthropic выпустила SKILL.md как открытый стандарт в октябре 2025 года, и к середине 2026-го экосистема выросла до сотен тысяч звёзд на GitHub. Формат сейчас читают не только Claude Code, но и Codex CLI, Cursor, Gemini CLI и ещё несколько инструментов — но специализированного линтера для проверки структуры пока нигде нет, слишком новая и нишевая область.
Ключевая идея — прогрессивное раскрытие
При старте агент видит только имя и краткое description каждой установленной skill — это буквально десятки токенов на skill. Полная инструкция подгружается лишь тогда, когда описание совпало с реальной задачей.
---
name: code-reviewer
description: Runs a structured review pass over code changes, checking logic simplification and reusable extraction
---
Full review instructions here, loaded only when this skill matches the task.Именно эта архитектура объясняет, почему библиотека из пятидесяти skills не замедляет агента заметно — большинство из них попросту не загружается целиком для конкретной задачи, участвует в работе только краткое описание.
Почему это не работает так же для CLAUDE.md
CLAUDE.md загружается целиком при каждом обращении к проекту, без разбора, релевантен ли он конкретной задаче. Пятьдесят skills — это пятьдесят коротких описаний плюс несколько полных загрузок по совпадению. Один разросшийся до нескольких тысяч строк CLAUDE.md — это полная загрузка каждый раз, вне зависимости от задачи.
| Формат | Что загружается всегда | Что загружается по необходимости |
|---|---|---|
| CLAUDE.md / AGENTS.md | Весь файл целиком | — |
| SKILL.md | Только name и description | Полное тело skill, reference-файлы |
Практический ориентир по размеру
Формальной спецификации на этот счёт нет, но неформальный ориентир сообщества — держать тело skill в пределах пятисот токенов, вынося всё длинное в bundled reference-файлы, которые агент читает отдельным шагом по необходимости, а не подгружает автоматически вместе с телом.
Частые проблемы структуры
Отсутствие обязательных полей name или description делает skill фактически нерабочей — агент не сможет понять по краткому сканированию, когда её стоит подгрузить. Слишком длинное или расплывчатое description тоже вредит — оно читается при каждом старте вместе с описаниями всех остальных установленных skills.
Как проверить свой SKILL.md
SKILL.md Validator & Token Budget Linter проверяет frontmatter и оценивает объём тела в токенах относительно рекомендованного ориентира. Если же контент растёт не внутри skill, а внутри самого AGENTS.md, стоит проверить, не пора ли часть вынести отдельно — AGENTS.md / SKILL.md Coexistence Auditor ищет разделы, которые больше похожи на разовую процедуру, чем на общее правило.
Итоговый чеклист
Progressive disclosure — ключевое архитектурное отличие SKILL.md от CLAUDE.md и AGENTS.md: краткое описание всегда, полное тело — только по совпадению с задачей.
Пятьсот токенов на тело skill — неформальный, но практический ориентир сообщества, а не жёсткий лимит формата.
Общие, действительно всегда нужные правила — в AGENTS.md, редкие процедуры под конкретный сценарий — кандидаты на отдельный SKILL.md.