Modern QA2026Анатомия файла SKILL.md
Join

Course › 01 Agent Skills for Browser Automation

Cutting-edge · Chapter 01

Анатомия файла SKILL.md

Updated Jul 2026

Двухчастная структура

Каждый навык — это один markdown-файл с YAML-метаданными и markdown-телом:

┌─────────────────────────────┐
│  ---                        │  ← Начало YAML-метаданных
│  name: my-skill             │
│  description: ...           │  ← Метаданные (сигнал для выбора)
│  allowed-tools: Bash,Read   │
│  ---                        │  ← Конец YAML-метаданных
│                             │
│  # Instructions             │
│  Step 1: Do this...         │  ← Тело в формате Markdown (инструкции выполнения)
│  Step 2: Then this...       │
└─────────────────────────────┘

YAML-метаданные: Сигнал для выбора

Обязательные поля

name (строка, макс. 64 символа)

  • Только строчные буквы, цифры, дефисы
  • Становится командой вызова: /my-skill или skill: "my-skill"
  • Должно быть уникальным среди всех установленных навыков
name: vibe-check  # Хорошо
name: Vibe Check  # Плохо — без пробелов и заглавных букв
name: vibe_check  # Плохо — без подчёркиваний

description (строка)

  • КЛЮЧЕВОЕ поле. Claude читает описания всех навыков, чтобы решить, какой навык соответствует намерению пользователя
  • Должно быть достаточно конкретным, чтобы отличаться от других навыков
  • Должно описывать возможность, а не реализацию
# Хорошо — сообщает Claude, когда использовать этот навык
description: |
  Browser automation via CLI. Navigate pages, click elements,
  fill forms, take screenshots, extract text from web pages.

# Плохо — слишком расплывчато, пересекается с другими навыками
description: "Helps with web stuff"

# Плохо — описывает реализацию, а не возможность
description: "Runs vibe-check commands using the Bash tool"

Необязательные поля

allowed-tools (строка через запятую)

  • Инструменты, которые навык может использовать, временно предоставляются на время выполнения
  • Без этого навык наследует текущие разрешения сессии
  • Поддерживает подстановочные знаки: Bash(git:*) разрешает только команды git
allowed-tools: Bash           # Может запускать любые shell-команды
allowed-tools: Read,Write     # Только чтение и запись файлов
allowed-tools: Bash,Read,Write,Glob,Grep  # Полный доступ

model (строка)

  • Переопределяет, какая модель Claude выполняет навык
  • Полезно для оптимизации затрат (использовать Haiku для простых навыков)
model: claude-haiku-4-5-20251001  # Дешевле, быстрее
model: claude-sonnet-4-5-20250929 # Сбалансировано

version (строка)

version: "1.0.0"

disable-model-invocation (булево значение)

  • Когда true, навык может быть вызван только явно (через /skill-name), никогда автоматически
disable-model-invocation: true

Тело Markdown: Инструкции по выполнению

Тело — это то, что Claude читает при вызове навыка. Оно должно быть структурировано для ИИ-агента, а не для человека-читателя.

Лучшие практики

  1. Начинайте с краткого описания в одну строку — Что делает этот навык?
  2. Перечисляйте команды в справочной таблице — Формат быстрого поиска
  3. Показывайте типовые паттерны — 80% случаев использования
  4. Включайте подсказки — Нюансы, которые агенту нужно знать
  5. Не более 500 строк — Длинные навыки раздувают контекст; выносите детали в /references/

Пример: Структура SKILL.md навыка vibe-check

# Vibium Browser Automation — CLI Reference

The `vibe-check` CLI automates Chrome via the command line.
The browser auto-launches on first use.

## Commands

### Navigation
- `vibe-check navigate <url>` — go to a page
- `vibe-check url` — print current URL
...

### Common Patterns

**Read a page:**
​```sh
vibe-check navigate https://example.com
vibe-check text
​```

## Tips
- All click/type/hover actions auto-wait for the element
- Use `vibe-check find` to inspect before interacting

Эта структура работает, потому что:

  • Агент может просканировать таблицу команд, чтобы найти нужное
  • Секция паттернов предоставляет готовые рабочие процессы
  • Подсказки предотвращают типичные ошибки

Прикреплённые ресурсы (необязательные каталоги)

Навыки могут включать дополнительные каталоги наряду с SKILL.md:

/scripts/ — Исполняемый код

my-skill/
├── SKILL.md
└── scripts/
    ├── setup.sh          # Запускается один раз при установке
    ├── validate.py       # Вызывается агентом через Bash
    └── generate-report.sh

Агент вызывает скрипты через Bash: bash {baseDir}/scripts/validate.py

/references/ — Документация, которую агент может прочитать

my-skill/
├── SKILL.md
└── references/
    ├── api-schema.json       # Загружается в контекст по требованию
    ├── selector-patterns.md  # Шпаргалка по CSS-селекторам
    └── error-codes.md        # Справочник по устранению проблем

Агент загружает справочники через инструмент Read: Read {baseDir}/references/error-codes.md

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

/assets/ — Шаблоны и статические файлы

my-skill/
├── SKILL.md
└── assets/
    ├── report-template.html  # Ссылка по пути, не загружается в контекст
    └── logo.png

Навык vibe-check в частности

Навык vibe-check намеренно минималистичен — только один файл SKILL.md без прикреплённых ресурсов:

skills/vibe-check/
└── SKILL.md    # ~100 строк. Это всё.

Это осознанное проектное решение:

  • CLI-бинарник Vibium берёт на себя всю сложность (управление браузером, интерактивность, BiDi-прокси)
  • Навыку нужно лишь научить агента интерфейсу команд
  • Скрипты не нужны, потому что vibe-check и есть скрипт
  • Справочники не нужны, потому что сам SKILL.md достаточно лаконичен

Это золотой стандарт для навыков-обёрток CLI: тонкий слой инструкций поверх мощного бинарника.

Как агент использует навык во время выполнения

Вот что происходит, когда вы говорите «Перейди на example.com и сделай скриншот»:

1. Пользователь: "Go to example.com and take a screenshot"

2. Claude читает доступные навыки → находит, что описание vibe-check совпадает

3. Claude вызывает: Skill(skill="vibe-check")

4. Система внедряет содержимое SKILL.md в контекст разговора

5. Claude теперь знает все 22 команды vibe-check

6. Claude выполняет через Bash:
   → vibe-check navigate https://example.com
   → vibe-check screenshot -o screenshot.png

7. Claude отвечает: "Done. Screenshot saved to screenshot.png"

Ключевое понимание: шаги 1-5 происходят прозрачно. Пользователь никогда не видит SKILL.md. Он видит только агента, управляющего браузером.

Тезис для собеседования

«Agent skills — это фундаментально другой архитектурный выбор по сравнению с MCP-серверами. Там, где MCP добавляет схемы инструментов в контекстное окно — часто тысячи токенов на каждый сервер — навыки внедряют процедурные знания как markdown. Навык vibe-check — это примерно 100 строк, которые обучают агента 22 браузерным командам. Те же возможности через MCP потребовали бы предоставления 22 отдельных определений инструментов с JSON-схемами, валидацией входных данных и форматами ответов. Skills — это "рецепты"; MCP — это "кухонное оборудование".»