Agent Skills (навыки агента)

Agent — это интеллектуальный агент, а Skills — навыки. Agent Skills — это ключевой инструмент, который превращает профессиональные знания и спецификации рабочих процессов в переиспользуемые ресурсы.

Agent Skills по сути представляет собой модульный Markdown-файл, который может научить инструменты ИИ (такие как Claude, GitHub Copilot, Cursor и т. д.) выполнять конкретные задачи, а также поддерживает автоматическое срабатывание, командный обмен и инженерное управление, полностью исключая повторяющийся ввод промптов.

Суть Agent Skills не в инструменте, а в:

Сочетание поведенческих норм + профессиональных знаний + момента использования.

Базовый справочный материал по Skills:Учебник по Skills

Основная форма:

• Skill — это папка, которая должна содержать файл SKILL.md (включая описание и метаданные) и может дополнительно содержать другие файлы ресурсов (например, скрипты, примеры, справочные документы).

• Skill — это файл Markdown (SKILL.md), используемый для обучения Claude делать всё по-вашему в конкретных сценариях.

• По сути, это равносильно выдаче профессионального руководства ИИ-агенту. ИИ не учится с нуля каждый раз, а автоматически обращается к знаниям из руководства в зависимости от задачи.

• Проще говоря, раньше мы использовали промпты, чтобы научить ИИ выполнять задачи; теперь с Agent Skills мы можем упаковывать промпты + ресурсы в переиспользуемые, совместно используемые пакеты навыков, делая работу более эффективной и надёжной.

Как работают Agent Skills

Ключ к Agent Skills — прогрессивное раскрытие, загружаемое в три слоя:

• Слой 1: Обнаружение навыков-- ИИ сначала читает метаданные (название и описание) всех навыков, чтобы определить, относится ли задача к ним. Эти метаданные всегда содержатся в системном промпте.
• Слой 2: Загрузка основных инструкций-- Если релевантно, ИИ автоматически читает основное содержимое файла SKILL.md, чтобы получить подробные указания.
• Слой 3: Загрузка файлов ресурсов-- Читать дополнительные файлы (например, скрипты, примеры) только при необходимости или выполнять скрипты через инструменты.

Поддерживаемые инструменты и среды

В настоящее время поддерживаются:

• Claude (Anthropic): Claude.ai, Claude Code, Agent SDK.
• VS Code + GitHub Copilot: навыки уровня проекта (.github/skills/) или личного уровня.
• Cursor: навыки уровня проекта (.cursor/skills/) или глобальные навыки, поддерживает установку из GitHub.
• Другие: расширяются, открытый стандарт наhttps://github.com/agentskills/agentskills。

Зачем нужны навыки? Какие проблемы они решают?

Обычные ИИ-агенты (такие как Claude или Copilot) умны, но они склонны к ошибкам при отсутствии конкретного контекста. Например:

• У команды есть собственные стандарты кодирования, но ИИ приходится напоминать вручную каждый раз.
• Для сложных процессов, таких как обработка PDF-форм или отладка GitHub Actions, ИИ может не знать лучших практик.

Agent Skills решает эти проблемы:

• Автоматическое срабатывание: ИИ автоматически загружает соответствующие навыки в зависимости от задачи, избавляя от необходимости вручную вводить длинные промпты.
• Повторно используемые и доступные для совместного использования: Создаётся один раз, используется всей командой или сообществом, поддерживает контроль версий Git.
• Эффективное использование контекста: Используйте прогрессивное раскрытие, загружая только необходимые части, чтобы избежать переполнения окна контекста.
• Кроссплатформенность: Один и тот же навык можно использовать в таких инструментах, как Claude, VS Code Copilot, Cursor и т. д.

Быстрое понимание основных концепций

Поток выполнения навыка

• Отталкиваясь от инструкции пользователя, сначала выполните распознавание намерения навыка, чтобы решить, следует ли переходить к контролируемому пути выполнения.

• После сопоставления навыка система загружает SKILL.md, устанавливает разрешения для инструментов и границы поведения, а затем рассуждает с учётом контекста.

• Вызывайте разрешённые внешние инструменты только при действительной необходимости; в противном случае завершайте логику в рамках правил.

• Итоговый результат выводится после интеграции ограничений, а следующий ввод пользователя запускает новый раунд полного процесса.

Минимальная структура навыка

my-skill/
└── SKILL.md   （唯一必需）

Базовый шаблон SKILL.md:

---
name: your-skill-name
description: What it does and when Claude should use it
---

# Skill Title

## Instructions
Clear, concrete, actionable rules.

## Examples
- Example usage 1
- Example usage 2

## Guidelines
- Guideline 1
- Guideline 2

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

Навыки поддерживают вставку динамических переменных в содержимое:

Например:

---
name: session-logger
description: 记录当前会话活动
---

请将以下内容写入日志文件：

logs/${CLAUDE_SESSION_ID}.log

$ARGUMENTS

Вызов:

/session-logger 用户登录成功

Он действительно будет создавать записи журнала, относящиеся к конкретной сессии.

Основные компоненты файла SKILL.md

Возьмём в качестве примера навык редактирования PDF-документов Claude: Claude может нативно разбирать PDF-файлы, но не может напрямую манипулировать ими (например, заполнять формы). Этот навык восполняет этот пробел.

• Основная форма:Каталог, содержащий SKILL.md
• Обязательные метаданные:Блок YAML в начале SKILL.md должен включать name и description; он предварительно загружается в системный промпт при запуске.

Многофайловый навык (прогрессивное раскрытие)

Механизм прогрессивного раскрытия

• Слой 1: метаданные → позволяют Claude оценить применимые сценарии для навыка без загрузки всего содержимого.
• Слой 2: тело SKILL.md → после определения релевантности загружается полный контекст.
• Уровень 3+: Присоединённые файлы (например, forms.md) → на которые ссылаются по мере необходимости, чтобы основной файл оставался компактным.

Следующая диаграмма показывает, как изменяется окно контекста, когда сообщение пользователя запускает навык:

• Начальное состояние: окно контекста содержит системную подсказку, метаданные навыка и инструкцию пользователя.
• Вызовите инструмент Bash, чтобы прочитать целевой SKILL.md и запустить соответствующий навык.
• Загружайте вспомогательные файлы по мере необходимости (например, forms.md).
• Выполните задачу пользователя после завершения загрузки.

Рекомендуемая структура каталогов

Чтобы избежать раздувания контекста:

• Основные правила →SKILL.md
• Подробные материалы → отдельные файлы
• Практическая логика → выполнение скрипта (не загружается)

Рекомендуемая структура:

my-skill/
├── SKILL.md
├── reference.md
├── examples.md    # 存放示例文件
└── scripts/
    └── helper.py

Ваш первый навык

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

Создайте каталог навыков

Навыки хранятся в~/.claude/skills/(личные глобальные) или в каталоге проекта.claude/skills/(для конкретного проекта).

В этой главе мы тестируем в каталоге проекта. Сначала создайте каталог claude-test:

mkdir claude-test

Перейдите в этот каталог, создайте каталог skills и файлы:

mkdir -p .claude/skills/python-naming-standard

Напишите файл конфигурации SKILL.md

Создайте SKILL.md в этом каталоге. Это мозг навыка, который сообщает Claude, когда его использовать.

---
name: Python 内部命名规范技能
description: 当用户要求重构、审查或编写 Python 代码时，请参考此规范。
---

## 指令
1. 所有的内部辅助函数必须以 `_internal_` 前缀命名。
2. 如果发现不符合此规则的代码，请自动提出修改建议。
3. 在执行 `claude commit` 前，必须检查此规范。

## 参考示例
- 正确：`def _internal_calculate_risk():`
- 错误：`def _calculate_risk():`

Требования к полям:

• name: Должно состоять только из строчных букв, цифр и дефисов (максимум 64 символа)
• description: Краткое описание навыка и того, когда его использовать (максимум 1024 символа)

После создания структура файлов выглядит так:

Теперь ваш проект должен выглядеть так:

my-project/
├─ src/
│  └─ test.py              # 项目源码
├─ .claude/
│  ├─ skills/
│  │  └─ hello-world/
│  │     ├─ skill.md       # Skill 定义（YAML + Instructions，机器可执行）
│  │     └─ README.md      # Skill 说明（人类阅读，可选）
│  └─ config.yml           # Claude 项目级配置（可选）
├─ .gitignore
└─ README.md               # 项目整体说明

Затем выполните следующую команду в терминале, чтобы запустить Claude Code:

claude

Введите задачу:

Help me write a function that calculates user discounts.

Claude просканирует установленные Skills, обнаружит, что ваш запрос связан с "написанием кода на Python", и сопоставит его с python-naming-standard.

Он сгенерирует следующий код в соответствии с требованиями в SKILL.md:

def _internal_get_discount(user_score):
    # 计算逻辑...
    return discount

Добавьте файлы ресурсов (необязательно)

Кроме того, мы можем.claude/skills/добавить следующие каталоги ниже:

В той же папке добавьте:

• examples/: хранит файлы примеров.
• references/: хранит справочные документы.
• scripts/: хранит исполняемые скрипты (например, Python для обработки PDF).

Затем укажите ссылки на них в SKILL.md:

查看示例 commit：./examples/good-commit.txt
运行脚本：使用工具执行 ./scripts/process.py

Официальный маркетплейс

Помимо создания собственных, вы также можете воспользоваться открытым стандартом Agent Skills, выпущенным в конце 2025 года:

• Официальный маркетплейс: посетитеhttps://github.com/anthropics/skillsрепозиторий, чтобы скачать готовые навыки (например, оптимизатор React, инструменты настройки SQL).
• Skill Creator: Вы можете сказать Claude: «Помоги мне обобщить логику конфигурации Docker, которую я только что тебе объяснил, в Skill», и он автоматически сгенерирует файлы для вас в соответствующем каталоге.

Мы можем зарегистрировать этот репозиторий как маркетплейс плагинов для Claude Code, просто выполнив следующую команду в Claude Code:

/plugin marketplace add anthropics/skills

Затем вы можете использовать/plugin для просмотра:

Шаги для установки конкретного набора навыков:

• Просмотрите и установите плагины

• Выберите источник плагина anthropic-agent-skills

• Выберите document-skills (навыки для документов) или example-skills (примеры навыков)

  

• Нажмите «Установить сейчас»

  

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

/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills

Примечание:Каталог skills, установленный через плагины, находится～/claude/plugins/marketplaces/под.

После завершения установки плагина необходимо перезапустить Claude Code.

При использовании достаточно указать название навыка в инструкции, чтобы вызвать его. Например, после установки плагина document-skills вы можете дать Claude Code следующую инструкцию:

使用 PDF 技能提取 path/to/some-file.pdf 文件中的表单字段

Или создайте PPT:

创建一个 Agent Skill 的演示文稿

Вы можете видеть, что он вызвал/document-skills:pptx：

начал генерировать:

Ресурсы, связанные с Agent Skills