Конфигурация и многофайловые навыки

Первый навык умещался в один файл и обходился двумя полями шапки. Настоящие командные навыки быстрее становятся сложнее: у них есть длинные справочники, скрипты, ограничения на инструменты и особые режимы запуска. В этом уроке — все нужные настройки и принцип «SKILL.md короткий, детали — в соседних файлах».

Поля шапки, которые вам понадобятся

Полный список есть в документации. Ниже — те, что решают реальные задачи.

Кто вызывает: четыре сочетания

Два булевых поля дают четыре режима.

• По умолчанию — и вы, и Claude. Описание в контексте, команда в меню. Для большинства рабочих навыков.
• disable-model-invocation: true — только вы. Для всего, что имеет побочные эффекты: деплой, рассылка, удаление. Claude не должен решать сам, что «пора выкатывать».
• user-invocable: false — только Claude. Для справочной информации: соглашения по API, описание архитектуры легаси-модуля. Человек такое командой не вызывает, а Claude подтянет, когда работает с этим кодом.
• Оба — навык выключен, но файл остаётся. Удобно на время отладки.

Инструменты: разрешить заранее или убрать

allowed-tools — это предварительное разрешение, а не ограничение. Инструменты из списка не будут спрашивать подтверждения на том ходу, когда навык вызван. Остальные инструменты никуда не деваются и по-прежнему подчиняются вашим настройкам прав. Грант действует один ход: на следующем вашем сообщении он сбрасывается, хотя текст навыка остаётся в контексте.

allowed-tools: Bash(git log *) Bash(git describe *) Bash(git diff *)

Так навык релиз-нот выполнит git log, не задавая вопросов, а вот git push спросит, как обычно.

disallowed-tools — наоборот, убирает инструменты из доступных, пока навык активен. Ограничение тоже снимается на следующем сообщении. Для навыка «только анализ» можно убрать Write и Edit.

Важная оговорка про безопасность. allowed-tools проектного навыка применяется всегда, когда навык вызван, — доверие к папке это не ограничивает. Навык из чужого репозитория может выдать себе широкие права. Прежде чем запускать Claude Code в клонированном проекте, посмотрите, что лежит в его .claude/skills/.

Навык в отдельном контексте

context: fork запускает навык не в текущем разговоре, а в субагенте: тело SKILL.md становится заданием, истории разговора субагент не видит. Это нужно, когда навык порождает много вывода — например, полный аудит доступности по сотне компонентов. Результат вернётся отчётом, а сто прочитанных файлов останутся за кадром.

---
name: a11y-audit
description: Полный аудит доступности директории с компонентами. Используй, когда просят проверить a11y, доступность или WCAG для целого раздела или проекта.
context: fork
agent: Explore
background: false
---

agent: Explore даёт быстрого субагента с правами только на чтение; он не читает CLAUDE.md, поэтому все правила должны быть в самом навыке. background: false заставляет дождаться результата, а не продолжать разговор параллельно. Подробнее о том, как субагенты работают, — в курсе «Субагенты в Claude Code».

Живые данные внутри навыка

Строка вида !`команда` в теле навыка выполняется до того, как Claude увидит текст, и её вывод подставляется на место. Так навык получает актуальные данные без лишнего хода:

## Коммиты с последнего тега
!`git log $(git describe --tags --abbrev=0)..HEAD --oneline`

Сгруппируй изменения выше по разделам шаблона.

Если команда завершилась с ошибкой, вызов навыка прерывается целиком и Claude тела не увидит. Для команд поиска вроде grep и git diff код возврата 1 («ничего не найдено») считается нормальным, а 2 и выше — ошибкой.

Многофайловый навык

Главное правило: SKILL.md не длиннее 500 строк, и в нём — только то, что нужно в каждом вызове. Всё остальное — в соседние файлы, на которые SKILL.md ссылается. Claude читает их, когда доходит до соответствующего шага, а не при каждом срабатывании. Так длинный справочник почти ничего не стоит, пока не понадобится.

Структура навыка проверки доступности:

.claude/skills/a11y-check/
├── SKILL.md            # порядок проверки и формат отчёта
├── checklist.md        # 20+ критериев WCAG с пояснениями
├── report-template.md  # шаблон отчёта для клиента
└── scripts/
    └── contrast.py     # считает контраст двух цветов

SKILL.md:

---
name: a11y-check
description: Проверяет доступность вёрстки по WCAG 2.1 AA. Используй, когда просят проверить a11y, доступность, контраст, подписи у полей или клавиатурную навигацию в компонентах или на странице.
allowed-tools: Bash(python3 ${CLAUDE_SKILL_DIR}/scripts/contrast.py *)
---

Проверь доступность файлов, которые указал пользователь: $ARGUMENTS.

1. Прочитай критерии в [checklist.md](checklist.md) и пройди по ним
   каждый файл.
2. Для каждой пары «цвет текста — цвет фона», которую найдёшь
   в стилях, посчитай контраст скриптом:
   `python3 ${CLAUDE_SKILL_DIR}/scripts/contrast.py "#333333" "#ffffff"`
   Не оценивай контраст на глаз.
3. Оформи результат по [report-template.md](report-template.md):
   для каждой проблемы — файл, строка, критерий, что сделать.
4. Ничего не исправляй. Если что-то не удалось проверить —
   напиши об этом отдельным разделом.

Ссылки на соседние файлы — обычные markdown-ссылки с относительным путём. Рядом с каждой стоит написать, зачем файл нужен, чтобы Claude понимал, когда его открывать.

${CLAUDE_SKILL_DIR} — путь к папке навыка. Он подставляется и в теле, и в allowed-tools, поэтому скрипт запускается без вопросов, где бы навык ни лежал. Есть ещё ${CLAUDE_PROJECT_DIR} — корень проекта.

Скрипт scripts/contrast.py — настоящий, считает отношение контраста по формуле WCAG:

#!/usr/bin/env python3
"""Контраст двух цветов по WCAG 2.1. Использование: contrast.py "#rrggbb2#rrggbb34
import sys


def channel(c: int) -> float:
    c = c / 255
    return c / 12.92 if c <= 0.03928 else ((c + 0.055) / 1.055) ** 2.4


def luminance(hex_color: str) -> float:
    h = hex_color.lstrip("#")
    if len(h) == 3:
        h = "".join(ch * 2 for ch in h)
    r, g, b = (int(h[i:i + 2], 16) for i in (0, 2, 4))
    return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b)


def contrast(a: str, b: str) -> float:
    la, lb = sorted((luminance(a), luminance(b)), reverse=True)
    return (la + 0.05) / (lb + 0.05)


if __name__ == "__main__":
    if len(sys.argv) != 3:
        sys.exit("usage: contrast.py '#rrggbb' '#rrggbb'")
    ratio = contrast(sys.argv[1], sys.argv[2])
    verdict = "AA" if ratio >= 4.5 else "AA (крупный текст)" if ratio >= 3 else "не проходит"
    print(f"{ratio:.2f}:1 — {verdict}")

Смысл скрипта не в том, что модель не умеет считать, а в том, что она считает ненадёжно. Красный #E0342B на белом даёт 4.47 — формально ниже порога 4.5, и «на глаз» это не видно. Скрипт даёт ответ, который можно вставить в отчёт клиенту.

Навык только для части проекта

Поле paths ограничивает автоматическое срабатывание файлами по шаблону:

paths: "src/components/**/*.tsx"

Навык проверки доступности не будет предлагаться, когда вы работаете с миграциями базы. Ручной вызов через / работает всегда.