Структура каталога навыков
Понимание структуры каталогов и механизма работы навыка — это основа для создания поддерживаемых и переиспользуемых возможностей AI-агента.
В этой статье разбираются структура каталогов, роль каждого файла и полный рабочий процесс стандартного навыка с нуля.
Что такое Skill
Навык — это независимая единица возможностей, предназначенная для выполнения задач определённого типа.
Если Агента сравнить с операционной системой, то навык подобен приложению; если Агента сравнить с руководителем проекта, то навык — это профессиональная возможность, которую можно вызвать.
Распространённые типы навыков
Ниже приведены некоторые типичные сценарии применения навыков:
| Type | Описание | Применимые сценарии |
|---|---|---|
| Анализ PDF-документов | Извлечение содержимого PDF и создание сводок | Обработка документов, извлечение информации |
| Веб-скрапинг | Автоматическое получение веб-данных | Сбор данных, мониторинг информации |
| Оптимизация SQL | Анализ и оптимизация SQL-запросов | Настройка производительности базы данных |
| Статистика данных | Вычисления и статистическая обработка данных | Анализ данных, формирование отчётов |
| Распознавание изображений | Распознавание содержимого изображений | OCR, классификация изображений |
Связь между навыком и агентом
Сам навык не отвечает за принятие решения о том, когда его использовать; именно агент фактически принимает это решение.
Полный рабочий процесс выглядит следующим образом:
Ключевой момент: агент не загружает всё содержимое всех навыков сразу. Сначала он читает описательную информацию каждого навыка и только после сопоставления с целевым навыком загружает полное содержимое. Причина этого такова: если навыков сотни, загрузка всех их каждый раз была бы крайне расточительной по отношению к токенам.
Стандартная структура каталогов навыка
Полноценный навык — это не один файл, а каталог, содержащий несколько файлов.
Ниже представлена полная структура каталогов стандартного навыка:
my-skill/ │ ├── SKILL.md ← 核心执行文件 ├── metadata.json ← 元信息 ├── examples/ ← 示例目录 │ ├── example1.md │ └── example2.md │ ├── scripts/ ← 可执行脚本 │ ├── main.py │ └── utils.py │ ├── resources/ ← 资源目录 │ ├── prompt.md │ └── config.yaml │ ├── tests/ ← 测试目录 │ ├── test_cases.md │ └── eval.yaml │ ├── README.md ← 使用说明 │ └── CHANGELOG.md ← 变更日志
Далее мы поочерёдно разберём назначение каждого файла и каталога.

SKILL.md: основной исполняемый файл
Это самый важный файл в навыке, определяющий всю логику выполнения навыка.
Он содержит следующую ключевую информацию:
| Раздел | Описание | Назначение |
|---|---|---|
| Описание | Функциональное описание навыка | Используется для сопоставления агентов |
| Когда использовать | Чётко определить применимые сценарии | Избежать ложных срабатываний |
| Когда НЕ использовать | Чётко определить неприменимые сценарии | Предотвращение конфликтов с другими навыками |
| Ввод | Определение формата входных данных | Стандартизация способа вызова |
| Инструкции | Этапы выполнения | Руководство по выполнению задачи |
| Вывод | Описание формата вывода | Обеспечение согласованности результатов |
Ниже приведён стандартизированный пример SKILL.md:
Пример
## Описание
Используется для анализа содержимого PDF и создания сводок.
## Когда использовать
Подходит для:
- Чтение PDF
- Извлечение краткого содержания
- Анализ содержимого
## Когда НЕ использовать
Не подходит для:
- Редактирование изображений
- Обработка видео
## Входные данные
PDF-файл
## Инструкции
1. Извлечь текст
2. Определить структуру главы
3. Обобщить основное содержание
4. Вывести ключевые пункты
## Вывод
Сводка в формате Markdown
Распространённые неверные стили написания
Многие новички пишут чрезмерно упрощённый SKILL.md, например:
Пример нерекомендуемого написания
Читать PDF
Обобщить содержание
Вернуть результат
Проблема этого стиля написания заключается в том, что он не знает, когда его использовать, не знает, когда его не использовать, формат вывода неясен, и легко возникает конфликт с другими навыками.
Качественный SKILL.md должен позволять агенту с первого взгляда определить: подходит ли этот навык для текущей задачи.
metadata.json: метаданные навыка
Этот файл предоставляет машиночитаемые структурированные данные, помогающие агенту быстро фильтровать навыки.
Пример
"name": "pdf-analyzer",
"version": "1.0.0",
"description": "Проанализировать PDF и создать сводку",
"tags": ["pdf", "summary"],
"category": "document"
}
Описания общих полей
| Поле | Назначение | Важность |
|---|---|---|
| name | Название навыка | Обязательный |
| description | Функциональное описание; агент полагается на него при сопоставлении | Наиболее важное |
| version | Номер версии | Рекомендуется |
| tags | Теги для удобного поиска | Рекомендуется |
| category | Категория | Optional |
| author | Автор | Optional |
| разрешения | Необходимые разрешения | Optional |
Среди них полеdescriptionявляется самым важным, потому что Агент обычно полагается на него при сопоставлении.
Процесс сопоставления примерно таков: после того как пользователь отправляет запрос, Агент сканирует описания всех навыков и, найдя подходящее описание, загружает полное содержимое навыка и выполняет его.
examples: Пример каталога
Многие разработчики игнорируют эту часть, но на самом деле она очень важна.
Структура каталогов
examples/ ├── example1.md ├── example2.md
Пример содержимого файла
Пример
Пожалуйста, помогите мне проанализировать этот PDF
Вывод:
# Сводка по документу
## Основное содержание
1. ...
2. ...
3. ...
Назначение примеров
| Назначение | Описание |
|---|---|
| Предоставляйте примеры Few-shot | Помогайте модели понять ожидаемое поведение с помощью примеров |
| Стандартизируйте формат вывода | Проясняйте структуру и стиль вывода с помощью примеров |
| Повышайте стабильность вывода | Уменьшайте случайность поведения и делайте результаты более предсказуемыми |
Эмпирически хорошие примеры часто эффективнее добавления дополнительных промптов.
scripts: Исполняемые скрипты
Навык — это не просто промпт; иногда для выполнения реальной работы необходимо фактически исполнить код.
Типичные сценарии, требующие скриптов, включают: чтение PDF, выполнение OCR, обращение к базам данных, обработка данных, построение графиков и т. д.
Структура каталогов
scripts/ ├── main.py └── utils.py
Пример Python-скрипта
Пример
# Функция: извлечение текстового содержимого из PDF-файла
from pypdf import PdfReader
# Открыть PDF-файл
reader = PdfReader("demo.pdf")
# Сохранить извлечённый текст
text = ""
# Перебрать каждую страницу и извлечь текст
for page in reader.pages:
text += page.extract_text()
# Вывести всё текстовое содержимое
print(text)
Рабочий процесс Skill таков: прочитать файл → выполнить скрипт → получить результат, затем передать результат большой модели для обработки.
resources: Каталог ресурсов
Используется для хранения вспомогательного содержимого, отделяя конфигурацию от кода.
Структура каталогов
resources/ ├── prompt.md ├── config.yaml
Возможные типы ресурсов
| Тип ресурса | Описание | Пример |
|---|---|---|
| Шаблон промпта | Многоразовые шаблоны промптов | prompt.md |
| Файл конфигурации | Параметры и настройки | config.yaml |
| Текстовые шаблоны | Шаблоны писем и отчётов | template.txt |
| Графические ресурсы | Иконки, диаграммы | logo.png |
| Шаблоны SQL | Предопределённые шаблоны запросов | query.sql |
Пример файла конфигурации
Пример
# Конфигурация, связанная со сводкой
max_length: 1000 # Максимальная длина сводки (символов)
language: zh # Язык вывода: zh=китайский, en=
Помещение параметров в файл означает, что не нужно изменять код при изменении параметров.
tests: Каталог тестов
Зрелые проекты обычно включают тесты, чтобы проверять эффективность и стабильность Skill.
Структура каталогов
tests/ ├── test_cases.md └── eval.yaml
Пример тест-кейса
Пример
Вход:
Помогите проанализировать PDF
Ожидаемый результат:
Вывести сводку
Включить ключевые моменты
Цель тестирования
| Назначение | Описание |
|---|---|
| Проверить эффективность | Убедиться, что вывод Skill соответствует ожиданиям |
| Регрессионное тестирование | После изменений убедиться, что старая функциональность не затронута |
| Автоматизированная оценка | Пакетное тестирование с автоматизированными рабочими процессами |
| A/B-тестирование | Сравнить качество вывода разных версий |
Навыки без тестирования подвержены проблеме «изменение одного предложения внезапно ломает старую функциональность».
README: инструкция по использованию
README предназначен для разработчиков: объясняет, как установить и использовать этот навык.
Пример
Скопируйте в каталог skills
# Использование
Загрузить PDF
# Формат вывода
Markdown
Основная проблема, которую он решает: в будущем даже автор может не знать, как использовать написанный им навык.
Полный пример: навык анализа PDF
Ниже приведён полный пример, объединяющий все вышеописанные концепции.
Обзор структуры каталогов
pdf-analyzer/ ├── SKILL.md ├── metadata.json ├── examples/ │ └── summary.md ├── scripts/ │ └── extract.py ├── tests/ │ └── eval.md └── README.md
Полный процесс вызова
用户:
上传 PDF 并总结
↓
Agent:
扫描所有 Skills
↓
发现:
description: 分析 PDF 并生成摘要
↓
命中 pdf-analyzer
↓
读取 SKILL.md
↓
调用 extract.py
↓
提取 PDF 内容
↓
生成摘要
↓
返回结果
Почему навыки следует проектировать как структуру каталогов?
Многие спрашивают: почему бы просто не использовать один prompt.txt для всего?
Причина в том, что при росте масштаба всё выходит из-под контроля.
Проблемы подхода с одним файлом
| Проблема | Конкретное проявление |
|---|---|
| Не поддерживаемо | Весь контент свален в один файл, что затрудняет внесение изменений |
| Не тестируемо | Нет тестовых случаев, поэтому вы не знаете, работает ли это после изменений |
| Не переиспользуемо | Каждый навык приходится писать с нуля |
| Нет управления версиями | Сложно отследить историю изменений |
| Нет совместной работы нескольких человек | Если несколько человек изменяют один файл, легко возникают конфликты |
Преимущества подхода на основе каталогов
| Преимущество | Способ реализации |
|---|---|
| Сопровождаемость | Каждый файл имеет чёткие обязанности, изменения легко локализовать |
| Переиспользуемость | Скрипты и конфигурации можно совместно использовать между Skills |
| Тестируемость | Отдельный каталог тестов, поддерживает автоматизированную проверку |
| Расширяемость | Добавление новых функций требует только добавления файлов |
| Возможность публикации | Каталог можно упаковать и распространять |
Итог
Skill — это по сути не промпт, а полноценный пакет программных возможностей.
Связи между основными файлами
SKILL.md
↓
定义行为
metadata.json
↓
定义信息
examples/
↓
定义示例
scripts/
↓
定义能力
tests/
↓
定义质量
README
↓
定义使用方式
Другие расширенияПромпт решает задачу лишь один раз, тогда как Skill превращает возможность в актив.