Система навыков Pi Agent Skills

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

Pi Agent реализуетстандарт Agent Skills。


Что такое Skill

Навык — это каталог, который содержитSKILL.mdфайл SKILL.md.

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

Можно представить навык как «профессиональное учебное руководство» для ИИ — обычно он не занимает место в контексте и загружается только при необходимости.


Как работают навыки

Весь процесс загрузки состоит из четырёх шагов, а основная идея — «сначала посмотреть каталог, затем прочитать полное содержимое».

  1. При запуске Pi Agent сканирует все расположения навыков и извлекает имена и описания.
  2. Описания всех доступных навыков встраиваются в системный промпт в формате XML.
  3. Когда задача пользователя совпадает с описанием навыка, ИИ автоматически загружает полный SKILL.md с помощью инструмента read.
  4. ИИ работает в соответствии с инструкциями в 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 можно отключить через настройки:

Пример

// Путь к файлу: ~/.pi/agent/settings.json
{
  "enableSkillCommands": false
}

Вы также можете использовать настройкуdisable-model-invocation, чтобы определённые Skills можно было вызывать только вручную и чтобы они не появлялись автоматически в системном промпте.


Импорт Skills из других инструментов

Pi Agent может загружать Skills из Claude Code или OpenAI Codex:

Следующие две конфигурации записываются соответственно в глобальный settings.json и settings.json проекта; скорректируйте пути в соответствии с вашими фактическими каталогами.

Пример

// Путь к файлу: ~/.pi/agent/settings.json (глобальный импорт)
{
  "skills": [
    "~/.claude/skills",
    "~/.codex/skills"
  ]
}

Для навыков Claude Code на уровне проекта:

Пример

// Путь к файлу: .pi/settings.json (импорт на уровне проекта)
{
  "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, транскрипция аудиоЗадачи, требующие получения данных из сети, автоматизированных операций и транскрипции мультимедиа
Другие расширения