Структура каталога навыков

Понимание структуры каталогов и механизма работы навыка — это основа для создания поддерживаемых и переиспользуемых возможностей AI-агента.

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


Что такое Skill

Навык — это независимая единица возможностей, предназначенная для выполнения задач определённого типа.

Если Агента сравнить с операционной системой, то навык подобен приложению; если Агента сравнить с руководителем проекта, то навык — это профессиональная возможность, которую можно вызвать.

Распространённые типы навыков

Ниже приведены некоторые типичные сценарии применения навыков:

TypeОписаниеПрименимые сценарии
Анализ PDF-документовИзвлечение содержимого PDF и создание сводокОбработка документов, извлечение информации
Веб-скрапингАвтоматическое получение веб-данныхСбор данных, мониторинг информации
Оптимизация SQLАнализ и оптимизация SQL-запросовНастройка производительности базы данных
Статистика данныхВычисления и статистическая обработка данныхАнализ данных, формирование отчётов
Распознавание изображенийРаспознавание содержимого изображенийOCR, классификация изображений

Связь между навыком и агентом

Сам навык не отвечает за принятие решения о том, когда его использовать; именно агент фактически принимает это решение.

Полный рабочий процесс выглядит следующим образом:

Skill 工作流程

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


Стандартная структура каталогов навыка

Полноценный навык — это не один файл, а каталог, содержащий несколько файлов.

Ниже представлена полная структура каталогов стандартного навыка:

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
- Извлечение краткого содержания
- Анализ содержимого

## Когда НЕ использовать

Не подходит для:

- Редактирование изображений
- Обработка видео

## Входные данные

PDF-файл

## Инструкции

1. Извлечь текст
2. Определить структуру главы
3. Обобщить основное содержание
4. Вывести ключевые пункты

## Вывод

Сводка в формате Markdown

Распространённые неверные стили написания

Многие новички пишут чрезмерно упрощённый SKILL.md, например:

Пример нерекомендуемого написания

# Навык PDF

Читать 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-скрипта

Пример

# Путь к файлу: scripts/extract.py
# Функция: извлечение текстового содержимого из 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

Пример файла конфигурации

Пример

# Путь к файлу: resources/config.yaml
# Конфигурация, связанная со сводкой

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 превращает возможность в актив.

Другие расширения