Настройки и навыки из нескольких файлов

Урок 3 из 7 курса «Навыки агентов»: официальный курс Anthropic Academy (Антропик) на русском языке. Этот урок бесплатный.

Примерное время: 20 минут

К концу этого урока вы сможете:

  • Настраивать расширенные поля метаданных навыка, включая allowed-tools и model
  • Писать эффективные описания навыков, которые надежно срабатывают на нужные запросы
  • Использовать allowed-tools для ограничения действий Claude, когда навык активен
  • Организовывать сложные навыки, используя прогрессивное раскрытие информации и многофайловые структуры

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

(4 минуты)

Это видео охватывает продвинутые методы, которые делают навыки более мощными: полный набор полей метаданных, как писать описания, которые надежно срабатывают, ограничение доступа к инструментам для рабочих процессов, чувствительных к безопасности, и организация более крупных навыков в нескольких файлах с использованием прогрессивного раскрытия информации. Вы узнаете, как поддерживать эффективность ваших навыков, при этом поддерживая сложные сценарии использования.

Основные выводы

  • name и description обязательны — allowed-tools и model необязательны, но являются мощными дополнениями
  • Хорошее описание отвечает на два вопроса: Что делает навык? Когда Claude должен его использовать?
  • allowed-tools ограничивает, какие инструменты Claude может использовать, когда навык активен — полезно для рабочих процессов только для чтения или чувствительных к безопасности
  • Прогрессивное раскрытие информации: держите SKILL.md менее 500 строк и ссылайтесь на вспомогательные файлы (references, scripts, assets), которые Claude читает только при необходимости
  • Скрипты выполняются без загрузки их содержимого в контекст — только вывод потребляет токены, сохраняя контекст эффективным

Базовый навык работает только с именем и описанием, но существует несколько продвинутых техник, которые могут сделать ваши навыки гораздо более эффективными в Claude Code. Давайте рассмотрим ключевые поля, лучшие практики для описаний, ограничения инструментов и способы структурирования более крупных навыков.

Поля метаданных навыка

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

  • name (обязательно) — Идентифицирует ваш навык. Используйте только строчные буквы, цифры и дефисы. Максимум 64 символа. Должно соответствовать имени вашей директории.
  • description (обязательно) — Указывает Claude, когда использовать навык. Максимум 1024 символа. Это самое важное поле, потому что Claude использует его для сопоставления.
  • allowed-tools (необязательно) — Ограничивает, какие инструменты Claude может использовать, когда навык активен.
  • model (необязательно) — Указывает, какую модель Claude использовать для навыка.

Написание эффективных описаний

Будьте точны в своих инструкциях. Если бы кто-то сказал вам "ваша работа — помогать с документами", вы бы не знали, что делать — и Claude думает так же.

Хорошее описание отвечает на два вопроса:

  1. Что делает навык?
  2. Когда Claude должен его использовать?

Если ваш навык не срабатывает, когда вы этого ожидаете, попробуйте добавить больше ключевых слов, которые соответствуют тому, как вы на самом деле формулируете свои запросы. Описание — это то, что Claude использует для определения релевантности навыка, поэтому язык имеет значение.

Ограничение инструментов с помощью allowed-tools

Иногда вам нужен навык, который может только читать файлы, но не изменять их. Это полезно для рабочих процессов, чувствительных к безопасности, задач только для чтения или любой ситуации, когда вам нужны защитные механизмы.

В этом примере поле allowed-tools установлено на Read, Grep, Glob, Bash. Когда этот навык активен, Claude может использовать только эти инструменты без запроса разрешения — без редактирования, без записи.

---
name: codebase-onboarding
description: Helps new developers understand the system works.
allowed-tools: Read, Grep, Glob, Bash
model: sonnet
---

Если вы полностью опустите allowed-tools, навык ничего не ограничивает. Claude использует свою обычную модель разрешений.

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

Навыки делят контекстное окно Claude с вашим разговором. Когда Claude активирует навык, он загружает содержимое этого SKILL.md в контекст. Но иногда вам нужны ссылки, примеры или служебные скрипты, от которых зависит навык.

Втискивание всего в один файл из 2000 строк имеет две проблемы: это занимает много места в контекстном окне, и это не весело поддерживать.

Прогрессивное раскрытие информации решает эту проблему. Держите основные инструкции в SKILL.md и помещайте подробные справочные материалы в отдельные файлы, которые Claude читает только при необходимости.

Открытый стандарт предлагает организовывать вашу директорию навыков следующим образом:

  • scripts/ — Исполняемый код
  • references/ — Дополнительная документация
  • assets/ — Изображения, шаблоны или другие файлы данных

Затем в SKILL.md ссылайтесь на вспомогательные файлы с четкими инструкциями о том, когда их загружать:

В этом примере Claude читает architecture-guide.md только тогда, когда кто-то спрашивает о дизайне системы. Если они спрашивают, куда добавить компонент, этот файл никогда не загружается. Это похоже на наличие оглавления в контекстном окне, а не всего документа.

Хорошее эмпирическое правило: держите SKILL.md менее 500 строк. Если вы превышаете это, подумайте, следует ли разделить содержимое на отдельные справочные файлы.

Эффективное использование скриптов

Скрипты в вашей директории навыков могут выполняться без загрузки их содержимого в контекст. Скрипт выполняется, и только вывод потребляет токены. Ключевая инструкция, которую нужно включить в ваш SKILL.md, — это указать Claude запустить скрипт, а не прочитать его.

Это особенно полезно для:

  • Валидации окружения
  • Преобразований данных, которые должны быть последовательными
  • Операций, которые более надежны как протестированный код, чем как сгенерированный код

Размышления об уроке

  • Подумайте о навыке, который вы хотели бы создать и который включает несколько файлов. Как бы вы структурировали SKILL.md по сравнению со вспомогательными справочными файлами?
  • Есть ли в вашей команде рабочие процессы, где ограничение доступа к инструментам с помощью allowed-tools добавило бы важный уровень безопасности?

Что дальше

В следующем уроке мы сравним навыки с другими способами настройки Claude Code — CLAUDE.md, субагентами, hooks и MCP серверами — чтобы вы могли выбрать правильный инструмент для каждой ситуации.

Обратная связь

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

Полезные гиды