Система навыков Pi Agent Skills
Навыки — это самодостаточные пакеты возможностей, которые позволяют ИИ по требованию загружать инструкции по рабочим процессам и скрипты инструментов для специализированных областей.
Pi Agent реализуетстандарт Agent Skills。
Что такое Skill
Навык — это каталог, который содержитSKILL.mdфайл SKILL.md.
SKILL.md содержит имя навыка, описание и подробные инструкции по использованию. ИИ автоматически прочитает и выполнит его при необходимости.
Можно представить навык как «профессиональное учебное руководство» для ИИ — обычно он не занимает место в контексте и загружается только при необходимости.
Как работают навыки
Весь процесс загрузки состоит из четырёх шагов, а основная идея — «сначала посмотреть каталог, затем прочитать полное содержимое».
- При запуске Pi Agent сканирует все расположения навыков и извлекает имена и описания.
- Описания всех доступных навыков встраиваются в системный промпт в формате XML.
- Когда задача пользователя совпадает с описанием навыка, ИИ автоматически загружает полный SKILL.md с помощью инструмента read.
- ИИ работает в соответствии с инструкциями в SKILL.md, используя относительные пути для ссылок на скрипты и ресурсы в каталоге навыка.
Обратите внимание, что модель может не прочитать его по собственной инициативе. При необходимости явно запросите его в промпте или используйте/skill:name, чтобы принудительно загрузить.
Этот подход называется "Progressive Disclosure" — в контексте всегда находятся только описания, а полные инструкции загружаются по требованию.
Структура каталога навыка
Обязателен только SKILL.md; остальные каталоги создаются по мере необходимости.
my-skill/
├── SKILL.md # 必需:Frontmatter + 指令
├── scripts/ # 辅助脚本
│ └── process.sh
├── references/ # 详细参考文档(按需加载)
│ └── api-reference.md
└── assets/
└── template.json
Формат SKILL.md
SKILL.md использует YAML Frontmatter для определения метаданных, затем следует тело инструкции в формате Markdown:
Пример
name: my-skill
description: Что делает этот навык и когда его использовать. Описание должно быть конкретным и ясным.
---
# Мой навык
## Установка
Запустите перед первым использованием:
```bash
cd ~/projects/brave-search-skill && npm install
```
## Использование
```bash
bash scripts/process.sh <input>
```
## Ссылки
См. [Справочное руководство](references/api-reference.md) для получения подробностей.
При ссылке на файлы в каталоге навыка используйтеотносительные пути。
Поля Frontmatter
Обязательны только name и description; добавляйте другие поля по мере необходимости.
| Поле | Обязательный | Описание |
|---|---|---|
| name | Да | До 64 символов, только строчные буквы/цифры/дефисы. Pi Agent не требует, чтобы имя совпадало с родительским каталогом. |
| description | Да | До 1024 символов. Описывает функцию навыка и когда его использовать. Это основа, по которой ИИ решает, загружать ли навык. |
| license | нет | Название лицензии |
| совместимость | нет | До 500 символов, требования к окружению. |
| metadata | нет | Пользовательские пары ключ-значение |
| allowed-tools | нет | Список предварительно одобренных инструментов (экспериментально) |
| disable-model-invocation | нет | Если установлено значение true, навык скрывается из системного промпта, и его можно вызвать только вручную через /skill:name. |
description — ключевая основа для принятия ИИ решения о загрузке вашего навыка, поэтому обязательно пишите его конкретно и ясно.
Расплывчатое описание может привести к тому, что навык будет срабатывать в неподходящих сценариях или игнорироваться там, где он нужен.
Расположения загрузки навыков
Pi Agent сканирует навыки как на глобальном уровне, так и на уровне проекта, с немного различающимися правилами обнаружения для разных расположений.
| Расположение | Область действия | Правила загрузки |
|---|---|---|
| ~/.pi/agent/skills/ | Глобальный | Файлы .md на корневом уровне и каталоги, содержащие SKILL.md, обнаруживаются рекурсивно. |
| ~/.agents/skills/ | Глобальный | Только каталоги, содержащие SKILL.md, обнаруживаются рекурсивно; файлы .md на корневом уровне игнорируются. |
| .pi/skills/ | Проект | Файлы .md на корневом уровне и каталоги, содержащие SKILL.md, обнаруживаются рекурсивно. |
| .agents/skills/ | Проект | Только каталоги, содержащие SKILL.md, обнаруживаются рекурсивно. |
| Пакеты Pi | Глобальный или проектный | Каталог skills/ или запись pi.skills в package.json. |
| CLI | Для текущего запуска | Путь --skill загружается явно, его можно передавать несколько раз. |
Ещё один момент: в ~/.agents/skills/ и .agents/skills/ проекта вложенные .md-файлы с корректным Frontmatter в сгруппированных подкаталогах также распознаются, а .md-файлы верхнего уровня без Frontmatter игнорируются.
Аргументы CLI--no-skillsАвтоматическое обнаружение навыков можно отключить, но явно указанныепути --skillвсё равно будут загружены.
Проверка и конфликты имён
Pi Agent проверяет навыки в соответствии со стандартом Agent Skills. Большинство проблем приводят только к предупреждениям, и навык всё равно загружается.
Файлы SKILL.md без описания не загружаются; некорректные файлы также вызывают только предупреждение и не загружаются.
Когда навыки с одинаковым именем поступают из разных расположений, выдаётся предупреждение и сохраняется первый обнаруженный.
Команды навыков
Каждый навык автоматически регистрируется как/skill:nameкоманда:
/skill:brave-search /skill:pdf-tools extract
Аргументы после команды будут добавлены к содержимому Skill в формеUser: argumentsи добавлены к содержимому Skill.
Используя /skill:pdf-tools extract report.pdf в качестве примера, развёрнутое содержимое примерно выглядит так:
/skill:pdf-tools extract report.pdf User: extract report.pdf
После получения этого содержимого ИИ будет следовать инструкциям в SKILL.md, чтобы найти и выполнить скрипты в каталоге scripts/.
Регистрацию команды Skill можно отключить через настройки:
Пример
{
"enableSkillCommands": false
}
Вы также можете использовать настройкуdisable-model-invocation, чтобы определённые Skills можно было вызывать только вручную и чтобы они не появлялись автоматически в системном промпте.
Импорт Skills из других инструментов
Pi Agent может загружать Skills из Claude Code или OpenAI Codex:
Следующие две конфигурации записываются соответственно в глобальный settings.json и settings.json проекта; скорректируйте пути в соответствии с вашими фактическими каталогами.
Пример
{
"skills": [
"~/.claude/skills",
"~/.codex/skills"
]
}
Для навыков Claude Code на уровне проекта:
Пример
{
"skills": ["../.claude/skills"]
}
Инструкции в навыках могут требовать от ИИ выполнения произвольных операций, включая запуск исполняемых файлов.
Перед использованием сторонних навыков рекомендуется ознакомиться с их содержимым.
Полный пример навыка
Ниже приведён полный пример навыка веб-поиска:
Пример
name: brave-search
description: Выполняет веб-поиск и извлечение контента через Brave Search API. Подходит для поиска документов, фактологических запросов или любого извлечения веб-контента.
---
# Brave Search
## Установка
Установите зависимости перед первым использованием:
```bash
cd ~/projects/brave-search-skill && npm install
```
## Поиск
```bash
# Запуск через node, разрешение на выполнение не требуется
node scripts/search.js "поисковый запрос" --content # включает содержимое страницы
node scripts/search.js "ключевое слово запроса" --content # включить содержимое страницы
# Если разрешение на выполнение уже предоставлено (chmod +x scripts/search.js), его также можно запустить напрямую.
./scripts/search.js "поисковое ключевое слово"
```
## Извлечение содержимого страницы
```bash
node scripts/content.js https://example.com
```
Рекомендуемые репозитории Skills
Эти два репозитория предоставляют большое количество готовых к использованию Skills, но перед установкой всё же рекомендуется ознакомиться с содержимым.
| Репозиторий | Направление контента | Применимые сценарии |
|---|---|---|
| Навыки Anthropic | Обработка документов (docx, pdf, pptx, xlsx), веб-разработка | Пакетная обработка повседневных офисных документов, разработка фронтенд-страниц |
| Навыки Pi | Веб-поиск, автоматизация браузера, Google API, транскрипция аудио | Задачи, требующие получения данных из сети, автоматизированных операций и транскрипции мультимедиа |