Синхронизация скиллов в AGENTS.md

Что вы сможете сделать после прохождения

Использовать openskills sync для создания файла AGENTS.md
Понять, как AI-агенты узнают о доступных скиллах через AGENTS.md
Выбирать скиллы для синхронизации и контролировать размер контекста AI
Использовать пользовательский путь вывода для интеграции с существующей документацией
Понимать формат XML AGENTS.md и методы использования

Предварительные знания

Этот учебник предполагает, что вы уже завершили установку первого скилла. Если вы ещё не установили ни одного скилла, пожалуйста, сначала выполните шаги установки.

Ваша текущая проблема

Возможно, вы уже установили некоторые скиллы, но:

AI-агент не знает о доступных скиллах: скиллы установлены, но AI-агенты (например, Claude Code) вообще не знают об их существовании
Не знаете, как сообщить AI о скиллах: слышали про AGENTS.md, но не знаете, что это такое и как создать
Боитесь, что слишком много скиллов займут контекст: установили много скиллов, но хотите выборочно синхронизировать, не хочется рассказывать AI о всех сразу

Корень этих проблем: установка скилла и доступность для AI — это разные вещи. Установка просто кладёт файлы на место, но чтобы AI узнал, нужно ещё синхронизировать в AGENTS.md.

Когда использовать этот подход

Синхронизация скиллов в AGENTS.md подходит для этих сценариев:

Только что установили скиллы, нужно сообщить AI-агенту об их существовании
После добавления новых скиллов обновить список доступных для AI
После удаления скиллов убрать из AGENTS.md
Хотите выборочно синхронизировать скиллы, контролировать размер контекста AI
Множественные агенты, нужен единый список скиллов

Рекомендуемая практика

После каждой установки, обновления или удаления скиллов выполняйте openskills sync, чтобы AGENTS.md соответствовал реальным скиллам.

🎒 Подготовка перед началом

Перед началом, пожалуйста, убедитесь:

[ ] Завершена установка хотя бы одного скилла
[ ] Вы находитесь в директории вашего проекта
[ ] Вы знаете место установки скиллов (project или global)

Предварительная проверка

Если скиллы ещё не установлены, сначала выполните:

bash

npx openskills install anthropics/skills

Основная идея: установка скилла ≠ доступность для AI

Управление скиллами в OpenSkills разделено на две фазы:

[Фаза установки]            [Фаза синхронизации]
Скилл → .claude/skills/  →  AGENTS.md
   ↓                           ↓
Файл существует          AI-агент читает
   ↓                           ↓
Локально доступен      AI знает и может вызвать

Ключевые моменты:

Фаза установки: используйте openskills install, скиллы копируются в директорию .claude/skills/
Фаза синхронизации: используйте openskills sync, информация о скиллах записывается в AGENTS.md
AI читает: AI-агент читает AGENTS.md, узнаёт о доступных скиллах
Загрузка по требованию: AI по мере необходимости использует openskills read <skill> для загрузки конкретного скилла

Зачем нужен AGENTS.md?

AI-агенты (например, Claude Code, Cursor) не сканируют файловую систему активно. Им нужен явный "список скиллов", сообщающий, какие инструменты можно использовать. Этот список — AGENTS.md.

Действуем пошагово

Шаг 1: Перейдите в директорию проекта

Сначала перейдите в директорию вашего проекта, где установлены скиллы:

bash

cd /path/to/your/project

Почему

openskills sync по умолчанию ищет установленные скиллы в текущей директории и создаёт или обновляет AGENTS.md в текущей директории.

Вы должны увидеть:

В директории вашего проекта должна быть директория .claude/skills/ (если вы установили скиллы):

bash

ls -la
# Пример вывода:
drwxr-xr-x  5 user  staff  .claude
drwxr-xr-x  5 user  staff  .claude/skills/
-rw-r--r--  1 user  staff  package.json

Шаг 2: Синхронизируйте скиллы

Используйте следующую команду для синхронизации установленных скиллов в AGENTS.md:

bash

npx openskills sync

Почему

Команда sync ищет все установленные скиллы, генерирует список скиллов в формате XML и записывает в файл AGENTS.md.

Вы должны увидеть:

Команда запустит интерактивный интерфейс выбора:

Found 2 skill(s)

? Select skills to sync to AGENTS.md:
❯ ◉ pdf                        (project)  Comprehensive PDF manipulation toolkit...
  ◉ git-workflow                (project)  Git workflow: Best practices for commits...
  ◯ check-branch-first          (global)   Git workflow: Always check current branch...

<Space> выбрать  <a> выбрать всё  <i> инвертировать  <Enter> подтвердить

Руководство по использованию:

┌─────────────────────────────────────────────────────────────┐
│  Инструкция                                                  │
│                                                             │
│  Шаг 1          Шаг 2           Шаг 3                       │
│  Переместить →  Пробел для выбора → Enter для подтверждения │
│                                                             │
│  ○ не выбрано      ◉ выбрано                                │
│                                                             │
│  (project)         скиллы проекта, подсвечены синим         │
│  (global)          глобальные скиллы, отображаются серым      │
└─────────────────────────────────────────────────────────────┘

Вы должны увидеть:
- Курсор может перемещаться вверх-вниз
- Нажатие пробела переключает состояние выбора (○ ↔ ◉)
- Скиллы проекта отображаются синим, глобальные — серым
- Нажатие Enter подтверждает синхронизацию

Умный предварительный выбор

Если это первая синхронизация, инструмент по умолчанию выберет все скиллы проекта. Если это обновление существующего AGENTS.md, инструмент предварительно выберет скиллы, уже включённые в файл.

Шаг 3: Выберите скиллы

В интерактивном интерфейсе выберите скиллы, которые вы хотите, чтобы AI-агент знал.

Пример:

Предположим, вы хотите синхронизировать все установленные скиллы:

? Select skills to sync to AGENTS.md:
❯ ◉ pdf                        (project)
  ◉ git-workflow                (project)
  ◯ check-branch-first          (global)   ← не выбираем этот глобальный скилл

Операции:

Переместить курсор: используйте стрелки вверх/вниз
Выбрать/снять выбор: нажмите пробел для переключения состояния (○ ↔ ◉)
Подтвердить синхронизацию: нажмите Enter для начала синхронизации

Вы должны увидеть:

✅ Synced 2 skill(s) to AGENTS.md

Стратегия выбора

Скиллы проекта: скиллы, специфичные для текущего проекта, рекомендуется синхронизировать
Глобальные скиллы: общие скиллы (например, стандарты кодирования), синхронизируйте по необходимости
Избегайте избытка: слишком много скиллов займут контекст AI, рекомендуется синхронизировать только часто используемые скиллы

Шаг 4: Просмотр AGENTS.md

После завершения синхронизации просмотрите сгенерированный файл AGENTS.md:

bash

cat AGENTS.md

Вы должны увидеть:

markdown

# AGENTS.md

<skills_system priority="1">

## Available Skills

<!-- SKILLS_TABLE_START -->
<usage>
When users ask you to perform tasks, check if any of available skills below can help complete the task more effectively.

How to use skills:
- Invoke: `npx openskills read <skill-name>` (run in your shell)
- The skill content will load with detailed instructions
- Base directory provided in output for resolving bundled resources

Usage notes:
- Only use skills listed in <available_skills> below
- Do not invoke a skill that is already loaded in your context
</usage>

<available_skills>

<skill>
<name>pdf</name>
<description>Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms...</description>
<location>project</location>
</skill>

<skill>
<name>git-workflow</name>
<description>Git workflow: Best practices for commits, branches, and PRs, ensuring clean history and effective collaboration.</description>
<location>project</location>
</skill>

</available_skills>
<!-- SKILLS_TABLE_END -->

</skills_system>

Описание ключевых элементов:

Элемент	Назначение
`<skills_system>`	XML-тег, сообщающий AI, что это определение системы скиллов
`<usage>`	Инструкции по использованию, объясняющие AI, как вызывать скиллы
`<available_skills>`	Список доступных скиллов
`<skill>`	Определение отдельного скилла
`<name>`	Название скилла
`<description>`	Описание скилла
`<location>`	Расположение скилла

Почему используется XML-формат?

XML-формат является стандартным для AI-агентов (особенно для Claude Code), что облегчает парсинг и понимание. Инструмент также поддерживает HTML-комментарии в качестве альтернативного формата.

Шаг 5: Проверьте чтение AI

Теперь попросите AI-агента прочитать AGENTS.md и посмотрите, знает ли он о доступных скиллах.

Пример диалога:

Пользователь:
Я хочу извлечь табличные данные из PDF-файла

AI-агент:
Я могу использовать скилл `pdf`, чтобы помочь вам извлечь табличные данные. Позвольте мне сначала прочитать подробное содержимое этого скилла.

Выполнение AI:
npx openskills read pdf

Вывод:
Skill: pdf
Base Directory: /path/to/project/.claude/skills/pdf

[Подробное содержимое скилла PDF...]

AI:
Хорошо, я загрузил скилл PDF. Теперь я могу помочь вам извлечь табличные данные...

Вы должны увидеть:

AI-агент распознаёт, что можно использовать скилл pdf
AI автоматически выполняет npx openskills read pdf для загрузки содержимого скилла
AI выполняет задачу согласно инструкциям скилла

Шаг 6 (опционально): Пользовательский путь вывода

Если вы хотите синхронизировать скиллы в другой файл (например, .ruler/AGENTS.md), используйте опцию -o или --output:

bash

npx openskills sync -o .ruler/AGENTS.md

Почему

Некоторые инструменты (например, Windsurf) могут ожидать AGENTS.md в определённой директории. Используя -o, вы можете гибко настраивать путь вывода.

Вы должны увидеть:

Created .ruler/AGENTS.md
✅ Synced 2 skill(s) to .ruler/AGENTS.md

Неинтерактивная синхронизация

В среде CI/CD вы можете использовать флаг -y или --yes, чтобы пропустить интерактивный выбор и синхронизировать все скиллы:

bash

npx openskills sync -y

Контрольная точка ✅

После выполнения описанных выше шагов, пожалуйста, подтвердите:

[ ] Интерактивный интерфейс выбора отображается в командной строке
[ ] Успешно выбран хотя бы один скилл (перед ним ◉)
[ ] Синхронизация успешна, отображается сообщение ✅ Synced X skill(s) to AGENTS.md
[ ] Файл AGENTS.md создан или обновлён
[ ] Файл содержит XML-тег <skills_system>
[ ] Файл содержит <available_skills> список скиллов
[ ] Каждый <skill> содержит <name>, <description>, <location>

Если все вышеперечисленные пункты выполнены, поздравляем! Скиллы успешно синхронизированы в AGENTS.md, и AI-агент теперь может узнавать о них и использовать их.

Предупреждения о возможных проблемах

Проблема 1: Скиллы не найдены

Проявление:

No skills installed. Install skills first:
  npx openskills install anthropics/skills --project

Причина:

В текущей директории или глобальной директории нет установленных скиллов

Решение:

Проверьте, установлены ли скиллы:

bash

npx openskills list

Если нет, сначала установите скиллы:

bash

npx openskills install anthropics/skills

Проблема 2: AGENTS.md не обновляется

Проявление:

После запуска openskills sync содержимое AGENTS.md не изменилось.

Причина:

Использован флаг -y, но список скиллов тот же, что и раньше
AGENTS.md существует, но синхронизируются те же скиллы

Решение:

Проверьте, использовали ли вы флаг -y

bash

# Уберите -y, войдите в интерактивный режим для повторного выбора
npx openskills sync

Проверьте, правильная ли текущая директория

bash

# Убедитесь, что вы в директории проекта, где установлены скиллы
pwd
ls .claude/skills/

Проблема 3: AI-агент не знает о скиллах

Проявление:

AGENTS.md сгенерирован, но AI-агент всё ещё не знает о доступных скиллах.

Причина:

AI-агент не прочитал AGENTS.md
Формат AGENTS.md некорректен
AI-агент не поддерживает систему скиллов

Решение:

Убедитесь, что AGENTS.md находится в корне проекта
Проверьте, правильный ли формат у AGENTS.md (содержит ли тег <skills_system>)
Убедитесь, поддерживает ли AI-агент AGENTS.md (например, Claude Code поддерживает, другим инструментам может потребоваться настройка)

Проблема 4: Файл вывода не markdown

Проявление:

Error: Output file must be a markdown file (.md)

Причина:

Использована опция -o, но указанный файл не имеет расширения .md

Решение:

Убедитесь, что файл вывода заканчивается на .md

bash

# ❌ Неправильно
npx openskills sync -o skills.txt

# ✅ Правильно
npx openskills sync -o skills.md

Проблема 5: Отмена всех выборов

Проявление:

В интерактивном интерфейсе, после отмены выбора всех скиллов, раздел скиллов в AGENTS.md удаляется.

Причина:

Это нормальное поведение. Если отменить выбор всех скиллов, инструмент удалит раздел скиллов из AGENTS.md.

Решение:

Если это было сделано по ошибке, снова запустите openskills sync и выберите скиллы для синхронизации.

Резюме урока

В этом уроке вы научились:

Использовать openskills sync для создания файла AGENTS.md
Понимать процесс синхронизации скиллов: установка → синхронизация → чтение AI → загрузка по требованию
Интерактивно выбирать скиллы, контролируя размер контекста AI
Использовать пользовательский путь вывода, интегрируясь с существующей системой документации
Понимать формат AGENTS.md, содержащий XML-тег <skills_system> и список скиллов

Основные команды:

Команда	Действие
`npx openskills sync`	Интерактивная синхронизация скиллов в AGENTS.md
`npx openskills sync -y`	Неинтерактивная синхронизация всех скиллов
`npx openskills sync -o custom.md`	Синхронизация в пользовательский файл
`cat AGENTS.md`	Просмотр содержимого созданного файла AGENTS.md

Ключевые моменты формата AGENTS.md:

Использует XML-тег <skills_system> для обёртки
Содержит <usage> инструкции по использованию
Содержит <available_skills> список скиллов
Каждый <skill> содержит <name>, <description>, <location>

Предварительный просмотр следующего урока

В следующем уроке мы изучим Использование скиллов.
Вы узнаете:
Как AI-агенты используют команду openskills read для загрузки скиллов
Полный процесс загрузки скиллов
Как читать несколько скиллов
Структуру и состав содержимого скиллов

Синхронизация скиллов — это только то, как сообщить AI о доступных инструментах. При реальном использовании AI будет загружать конкретное содержимое скиллов через команду openskills read.

Приложение: Справочник по исходному коду

Нажмите, чтобы развернуть и посмотреть расположение исходного кода

Время обновления: 2026-01-24

Функция	Путь к файлу	Номера строк
Точка входа команды sync	`src/commands/sync.ts`	18-109
Проверка файла вывода	`src/commands/sync.ts`	19-26
Создание несуществующего файла	`src/commands/sync.ts`	28-36
Интерактивный интерфейс выбора	`src/commands/sync.ts`	46-93
Разбор существующего AGENTS.md	`src/utils/agents-md.ts`	6-18
Генерация XML скиллов	`src/utils/agents-md.ts`	23-62
Замена раздела скиллов	`src/utils/agents-md.ts`	67-93
Удаление раздела скиллов	`src/utils/agents-md.ts`	98-122

Ключевые функции:

syncAgentsMd() - синхронизация скиллов в файл AGENTS.md
parseCurrentSkills() - разбор имён скиллов из существующего AGENTS.md
generateSkillsXml() - генерация списка скиллов в формате XML
replaceSkillsSection() - замена или добавление раздела скиллов в файл
removeSkillsSection() - удаление раздела скиллов из файла

Ключевые константы:

AGENTS.md - имя файла вывода по умолчанию
<skills_system> - XML-тег, используемый для маркировки определения системы скиллов
<available_skills> - XML-тег, используемый для маркировки списка доступных скиллов

Важная логика:

По умолчанию предварительно выбираются существующие в файле скиллы (инкрементальное обновление)
При первой синхронизации по умолчанию выбираются все скиллы проекта
Поддерживаются два формата маркировки: XML-теги и HTML-комментарии
При отмене всех выборов раздел скиллов удаляется, а не сохраняется пустым

Синхронизация скиллов в AGENTS.md ​

Что вы сможете сделать после прохождения ​

Ваша текущая проблема ​

Когда использовать этот подход ​

🎒 Подготовка перед началом ​

Основная идея: установка скилла ≠ доступность для AI ​

Действуем пошагово ​

Шаг 1: Перейдите в директорию проекта ​

Шаг 2: Синхронизируйте скиллы ​

Шаг 3: Выберите скиллы ​

Шаг 4: Просмотр AGENTS.md ​

Шаг 5: Проверьте чтение AI ​

Шаг 6 (опционально): Пользовательский путь вывода ​

Контрольная точка ✅ ​

Предупреждения о возможных проблемах ​

Проблема 1: Скиллы не найдены ​

Проблема 2: AGENTS.md не обновляется ​

Проблема 3: AI-агент не знает о скиллах ​

Проблема 4: Файл вывода не markdown ​

Проблема 5: Отмена всех выборов ​

Резюме урока ​

Предварительный просмотр следующего урока ​

Приложение: Справочник по исходному коду ​

Синхронизация скиллов в AGENTS.md

Что вы сможете сделать после прохождения

Ваша текущая проблема

Когда использовать этот подход

🎒 Подготовка перед началом

Основная идея: установка скилла ≠ доступность для AI

Действуем пошагово

Шаг 1: Перейдите в директорию проекта

Шаг 2: Синхронизируйте скиллы

Шаг 3: Выберите скиллы

Шаг 4: Просмотр AGENTS.md

Шаг 5: Проверьте чтение AI

Шаг 6 (опционально): Пользовательский путь вывода

Контрольная точка ✅

Предупреждения о возможных проблемах

Проблема 1: Скиллы не найдены

Проблема 2: AGENTS.md не обновляется

Проблема 3: AI-агент не знает о скиллах

Проблема 4: Файл вывода не markdown

Проблема 5: Отмена всех выборов

Резюме урока

Предварительный просмотр следующего урока

Приложение: Справочник по исходному коду