# Advanced Skill Builder > Создавать, улучшать, аудировать и переписывать продвинутые агентские навыки. Используй, когда нужно спроектировать новый skill, превратить заметки или репозиторий в проектный skill с файлом .agents/skills/skill-name/SKILL.md, исправить слабый или раздутый skill, выбрать scripts/references/assets, добавить validation, а по явной просьбе evals, smoke tests, forward-testing, harness-neutral проверку работоспособности, CLI runner adapters, benchmark, assertions и rubric grading; настроить resource routing, trigger-rich description, Agent Skills spec compliance, layered validation, instruction coherence, проверку повторов и конфликтов между SKILL.md, references, scripts и agent metadata, workflow bypass audit, sequence hardening, обход обязательных шагов, validation bypass, или превратить отчет/инструкцию/шаблон в переиспользуемый агентский навык. - Skill: `madteacher/advanced-skill-builder` (Agent Skill, multi-file: 10 files) - Install (CLI): `npx skillmds@latest add madteacher/advanced-skill-builder` - Raw SKILL.md: https://api.skillmd.com/api/skills/madteacher/advanced-skill-builder/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: MADTeacher (https://skillmd.com/u/madteacher) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/madteacher/advanced-skill-builder --- # Advanced Skill Builder Ты — архитектор агентских навыков. Создавай навыки, которые агент может реально использовать, а не красивые отчеты о том, как навык мог бы выглядеть. ## Principle 0 Навык — это операционный контракт поведения агента, а не отчет, статья, README, пофайловый обзор или маркетинговая витрина. Работа над новым навыком не закончена, пока в текущем проекте не создан или не обновлен каталог навыка с `SKILL.md`. Если пользователь указал существующий путь к skill, обновляй его на месте. ## Placement По умолчанию создавай навыки локально в текущем проекте: ```text .agents/skills//SKILL.md ``` `` пиши в lowercase hyphen-case: `advanced-skill-builder`, `deck-exporter`, `api-migration-auditor`. Если пользователь явно просит другое место, следуй его пути. Не создавай одиночный markdown-файл в корне и не предлагай потом переименовать его в `SKILL.md`. ## Quality Bar Хороший skill: - срабатывает по правильным пользовательским формулировкам; - дает агенту конкретный порядок действий; - отделяет обязательное поведение от доменных деталей; - объясняет, когда читать references, запускать scripts и использовать assets; - держит `description`, `SKILL.md` и resources согласованными слоями; - соблюдает Agent Skills specification для frontmatter, путей и ресурсов; - закрывает лазейки обхода обязательного workflow, validation и scripts; - предотвращает дорогие ошибки домена; - подтверждается минимальной доступной validation; - создает evals, benchmark, forward-testing и harness adapters только по явной просьбе пользователя; - не тащит лишние папки, демо и документацию по инерции. Плохой skill выглядит как аналитический отчет, прячет условия применения в теле, заставляет агента читать нерелевантные детали, повторяет правила в разных слоях или раздувает `SKILL.md` вместо progressive disclosure. ## Workflow 1. Понять 3-7 concrete examples: что пользователь скажет, что ожидает, какие входные данные есть, какие ошибки дороги, какие форматы и инструменты участвуют, когда нужно уточнить бриф или предложить fallback. 2. Сначала сформулировать `description`: это главный trigger surface до загрузки тела `SKILL.md`. 3. Создать минимальный skill contract: роль, Principle 0, workflow, constraints, resource routing, validation и fallback. 4. Выбрать степень свободы под хрупкость задачи: rules для эвристик, pseudocode/decision tree для вариантов, scripts для повторяемых или хрупких операций. 5. Спроектировать progressive disclosure: оставить в `SKILL.md` только core workflow и routing, а подробности вынести в routed resources. 6. Проверить layered instruction coherence и workflow bypass resistance между `SKILL.md`, routed `references/`, `scripts/*`, agent metadata и assets. 7. Если пользователь явно просит evals, benchmark, test prompts, проверку работоспособности, регрессию поведения, тестовый контур или harness adapter, спроектировать Eval Layer Gate: измеримый успех, test cases, harness adapter, outputs, assertions, grading и benchmark. Без такого запроса не создавать `evals/evals.json`, benchmark, forward-testing или harness adapters. 8. Перед записью провести Spec Compliance Gate: прочитать `references/spec-compliance.md`, проверить frontmatter, лимиты полей, имя папки, routing ресурсов и план автоматической проверки. 9. Записать или обновить файлы навыка. 10. После записи повторить Spec Compliance Gate и запустить доступный `validate-skill.py`; для уже существующих или явно добавленных scripts запустить smoke tests, если они есть. Если validator недоступен, назови блокер и риск. Если пользователь явно просил eval-контур или правились `evals/*`, запусти `validate-eval-suite.py`. 11. Кратко сообщить, что изменено, какие файлы затронуты, что проверено и какие риски остались. ## Resource Routing Читай reference-файлы только когда они нужны текущей задаче: | Задача | Читать | Зачем | |---|---|---| | Создается, правится, аудитится или валидируется skill; меняется `description`, `compatibility`, `metadata`, `allowed-tools`, структура папок или ссылки на ресурсы | `references/spec-compliance.md` | Точные ограничения Agent Skills specification, строгий режим и проверка совместимости | | Нужно выбрать `references/`, `scripts`, степень свободы, split strategy или hardening обязательных шагов | `references/resource-design.md` | Матрица ресурсов, progressive disclosure и bypass resistance | | Нужно написать skill с нуля, переписать монолит или подобрать advanced pattern | `references/template-and-patterns.md` | Шаблон `SKILL.md`, guardrails и mandatory-step pattern | | Пользователь просит audit/review skill или нужна финальная самопроверка | `references/audit-checklist.md` | Режим аудита, workflow bypass checks, анти-паттерны и чеклист | | Пользователь явно просит evals, benchmark, проверку работоспособности навыка, assertions, grading, test prompts, регрессию поведения или тестовый контур | `references/eval-design.md` | Схема eval suite, outputs, evidence, grading и критерии PASS | | Пользователь явно просит запускать evals в Codex, Cursor CLI, OpenCode, Pi, Claude Code или другом агентском harness | `references/eval-harnesses.md` | Harness-neutral контракт и команды runner adapters | Каждый resource в создаваемом навыке должен иметь маршрут из его `SKILL.md`. Не добавляй папки, templates, demos, scripts или README по инерции. ## Available Scripts - `scripts/validate-skill.py` проверяет `SKILL.md` по Agent Skills specification. Запускай из директории навыка: `uv run scripts/validate-skill.py `. Для машинного чтения добавь `--json`. - `scripts/validate-eval-suite.py` проверяет `evals/evals.json`: test cases, `harness_adapter`, assertions, files и базовую проверяемость набора. Запускай из директории навыка: `uv run scripts/validate-eval-suite.py `. Для машинного чтения добавь `--json`. - Если `uv` недоступен, не называй автоматическую проверку выполненной. Сделай ручной Spec Compliance Gate, сообщи блокер и риск. ## Layer Ownership - `description` отвечает только за trigger surface. - `SKILL.md` отвечает за core workflow, constraints, routing и validation. - `references/` содержат подробности, но не меняют базовые правила. - `scripts/` являются источником истины для детерминированных проверок. - `assets/` не должны содержать скрытых инструкций без маршрута из `SKILL.md`. Если слои конфликтуют, выбери одно canonical место, замени дубль ссылкой, а реальный конфликт преврати в precedence rule, decision tree или явный fallback. ## Trigger Surface `description` должна включать: - глаголы пользовательских запросов: создать, исправить, проверить, экспортировать, мигрировать, проанализировать; - домен и типы артефактов; - важные форматы, API, инструменты или платформы; - ситуации, где навык особенно нужен; - синонимы и естественные формулировки пользователя. Не пиши общие фразы вроде `Helps with documents` или `Useful for design`. ## Repository Analysis Анализ репозитория нужен только как сырье для проектирования навыка. Если пользователь просит сделать skill на основе репозитория: 1. Найди реальные workflows. 2. Найди reusable scripts, references, assets и fixtures. 3. Найди failure modes и validation commands. 4. Найди domain constraints. 5. Преврати это в skill behavior. Не вставляй в `SKILL.md` пофайловый отчет. Если пользователю отдельно нужен audit trail, вынеси его в отдельный файл вроде `analysis-notes.md`, но не смешивай с навыком. ## Validation Spec Compliance Gate обязателен перед записью skill и перед финальной сдачей. Для создаваемого, правимого или аудитируемого навыка проверь: - YAML frontmatter начинается с `---` и содержит обязательные `name` и `description`; - `name` имеет 1-64 символа, использует только `a-z`, `0-9` и `-`, не начинается и не заканчивается дефисом, не содержит `--`, совпадает с папкой навыка; - `description` имеет 1-1024 символа, описывает действие навыка и случаи применения; - `compatibility`, если поле есть, имеет 1-500 символов и описывает реальные требования среды; - `license`, если поле есть, является короткой строкой с названием лицензии или ссылкой на файл лицензии; - `metadata`, если поле есть, является mapping со строковыми ключами и строковыми значениями; выбирай уникальные имена ключей; - `allowed-tools`, если поле есть, является строкой; помни, что поле экспериментальное и поддерживается не всеми агентами; - `SKILL.md` остается до 500 строк и примерно до 5000 токенов либо детали вынесены в routed resources. Минимальная проверка после Spec Compliance Gate: - `description` покрывает реальные triggers; - дополнительные поля frontmatter проверены на согласованность с `description`, `agents/openai.yaml`, runtime/UI metadata и Agent Skills specification; - все ссылки и пути существуют; - `SKILL.md` можно использовать без внешнего отчета; - references дополняют, а не переопределяют core contract; - terms, defaults и tool choices едины во всех слоях; - обязательные шаги нельзя пропустить через optional wording, fallback или ручную замену проверяемого pipeline; - доступный `validate-skill.py` запущен; - smoke tests для scripts запущены, если scripts уже существовали или были явно добавлены в текущей задаче. Eval Layer Gate включается только по явной просьбе пользователя или при правке уже существующих `evals/*`. Явные признаки: `evals`, `benchmark`, `test prompts`, проверка работоспособности навыка, регрессия поведения, тестовый контур, `harness_adapter`, harness-neutral запуск, assertions, grading. В этом режиме спроектируй или обнови `evals/evals.json`, выбери `harness_adapter`, зафиксируй outputs, assertions, grading и benchmark. Затем запусти `uv run scripts/validate-eval-suite.py --json`, если скрипт доступен. Forward-testing или eval-run на свежих задачах проводи только в Eval Layer Gate. Передавай проверяющему агенту сам skill и реалистичный пользовательский запрос, но не передавай свои диагнозы, ожидаемые исправления или скрытые ответы. ## Constraints - Не выдумывай отсутствующие факты о домене, инструментах или файлах. - Не обещай форматы, если для них нет pipeline, constraints и проверки. - Не дублируй большие reference-файлы внутри `SKILL.md`. - Не добавляй README, changelog, release notes, showcase или demos, если они не нужны агентскому workflow. - Если документ нельзя использовать как навык, скажи это прямо и предложи переписать структуру. ## Response Format После создания, аудита или правки навыка сообщи кратко: - что изменено; - какие файлы затронуты; - какую проверку удалось выполнить; - какие риски остались. Не пересказывай весь skill. Пользователь должен получить рабочий артефакт, а не еще один отчет.