Устройство артефакта

Артефакт (скилл) — это файл SKILL.md с инструкциями, который агент добавляет в свой набор. Ключевое отличие от CLAUDE.md: описание скилла лежит в контексте всегда, а тело грузится только при вызове. Поэтому длинный справочный материал в скилле почти ничего не стоит, пока не понадобился.

Создавайте скилл, когда одну и ту же инструкцию или процедуру вы вставляете в чат повторно, или когда раздел CLAUDE.md вырос из факта в процедуру.

Где живёт

При совпадении имён корпоративный перебивает личный, личный — проектный. Плагинные живут в своём пространстве имён плагин:скилл и ни с кем не конфликтуют. Файлы из старого каталога .claude/commands/ продолжают работать и создают ту же команду /имя, но при совпадении имени побеждает скилл.

Отдельно: скиллы из вложенных .claude/skills/ не загружаются при старте. Они появляются, когда агент впервые прочитает или отредактирует файл в этом подкаталоге, — и до этого момента их нет ни в автодополнении, ни по имени.

Frontmatter

Все поля необязательны; рекомендуется только description — по нему агент решает, когда скилл применить.

---
name: commit
description: Собрать и закоммитить текущие изменения
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

Самые нагруженные поля:

Про allowed-tools есть неочевидная деталь безопасности: доверие рабочей области его не сдерживает. Проектный скилл применит своё предразрешение и в папке, которую вы никогда не помечали доверенной, и даже в прогоне -p. Скиллы, приехавшие вместе с чужим репозиторием, стоит прочитать до запуска (Круг дозволенного).

Прогрессивное раскрытие

Держите SKILL.md до 500 строк, а подробности выносите в соседние файлы, на которые ссылаетесь из тела:

my-skill/
├── SKILL.md        обзор и навигация
├── reference.md    подробности API — читается по надобности
├── examples.md     примеры
└── scripts/
    └── helper.py   исполняется, а не читается

Скрипты — самая недооценённая часть: скилл может нести исполняемый код на любом языке, и агент его запускает, а не загружает в котёл.

Жизненный цикл содержимого

При вызове отрендеренный SKILL.md входит в разговор одним сообщением и остаётся там на следующих ходах. Файл повторно не перечитывается. Отсюда практическое правило: пишите указания как постоянные («всегда делай так»), а не как одноразовые шаги.

При повторном вызове с тем же содержимым добавляется короткая пометка, что скилл уже загружен, а не вторая копия. Если аргументы изменились — вставляется полный текст заново.

Предразрешение из allowed-tools живёт иначе, чем текст: оно снимается, как только вы отправляете следующее сообщение. Чтобы разрешить инструменты на всю сессию, нужны обычные правила разрешений.

После сжатия контекста тела вызванных скиллов вставляются обратно — до 5000 токенов на скилл и 25 000 суммарно, обрезка сохраняет начало файла (Котёл).

Дальше: как отдать артефакт другим — Раздача артефактов; почему он молчит — Почему артефакт молчит. Если процедура должна выполняться в отдельном окне, соседняя механика — Тени, а факты, нужные в каждой сессии, остаются в Скрижаль проекта.