Пользовательский путь вывода

Что вы сможете сделать после изучения

Использовать флаг -o или --output для синхронизации навыков в файл .md в любом месте
Понять, как инструмент автоматически создает несуществующие файлы и каталоги
Настроить разные AGENTS.md для разных инструментов (Windsurf, Cursor и др.)
Управлять списком навыков в многофайловой среде
Пропустить стандартный AGENTS.md и интегрироваться в существующую систему документации

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

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

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

Возможно, вы уже привыкли к тому, что openskills sync по умолчанию создает AGENTS.md, но можете столкнуться с:

Инструмент требует определенный путь: Некоторые AI-инструменты (например, Windsurf) ожидают AGENTS.md в определенном каталоге (например, .ruler/), а не в корне проекта
Конфликт нескольких инструментов: Одновременное использование нескольких инструментов кодирования, которые могут ожидать AGENTS.md в разных местах
Интеграция с существующей документацией: У вас уже есть документ со списком навыков, и вы хотите интегрировать навыки OpenSkills в него, а не создавать новый файл
Каталог не существует: Вы хотите вывести вложенный каталог (например, docs/ai-skills.md), но каталог еще не существует

Корень этих проблем: путь вывода по умолчанию не удовлетворяет все сценарии. Вам нужен более гибкий контроль вывода.

Когда использовать этот прием

Пользовательский путь вывода подходит для этих сценариев:

Многоинструментальная среда: Настройка независимых AGENTS.md для разных AI-инструментов (например, .ruler/AGENTS.md против AGENTS.md)
Требования структуры каталогов: Инструмент ожидает AGENTS.md в определенном каталоге (например, .ruler/ в Windsurf)
Интеграция с существующей документацией: Интеграция списка навыков в существующую систему документации вместо создания нового AGENTS.md
Организационное управление: Классификация и хранение списков навыков по проектам или функциям (например, docs/ai-skills.md)
CI/CD среда: Использование фиксированного пути вывода в автоматизированных процессах

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

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

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

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

[ ] Завершена установка хотя бы одного навыка
[ ] Вы находитесь в каталоге вашего проекта
[ ] Вы знаете базовое использование openskills sync

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

Убедитесь, что у вас есть установленные навыки:

bash

npx openskills list

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

bash

npx openskills install anthropics/skills

Основная идея: гибкий контроль вывода

Функция синхронизации OpenSkills по умолчанию выводит в AGENTS.md, но вы можете использовать флаг -o или --output для настройки пользовательского пути вывода.

[Поведение по умолчанию]                    [Пользовательский вывод]
openskills sync      →      AGENTS.md (корень проекта)
openskills sync -o custom.md →  custom.md (корень проекта)
openskills sync -o .ruler/AGENTS.md →  .ruler/AGENTS.md (вложенный каталог)

Ключевые особенности:

Произвольный путь: можно указать любой путь к файлу .md (относительный или абсолютный)
Автоматическое создание файла: если файл не существует, инструмент автоматически создает его
Автоматическое создание каталога: если каталог файла не существует, инструмент рекурсивно создает его
Умный заголовок: при создании файла автоматически добавляется заголовок на основе имени файла (например, # AGENTS)
Проверка формата: должен заканчиваться на .md, иначе будет ошибка

Зачем нужна эта функция?

Разные AI-инструменты могут иметь разные ожидаемые пути:

Инструмент	Ожидаемый путь	Доступен ли путь по умолчанию
Claude Code	`AGENTS.md`	✅ Доступен
Cursor	`AGENTS.md`	✅ Доступен
Windsurf	`.ruler/AGENTS.md`	❌ Недоступен
Aider	`.aider/agents.md`	❌ Недоступен

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

Следуйте за мной

Шаг 1: Базовое использование - вывод в текущий каталог

Сначала попробуйте синхронизировать навыки в пользовательский файл в текущем каталоге:

bash

npx openskills sync -o my-skills.md

Почему

Использование -o my-skills.md сообщает инструменту вывести в my-skills.md вместо стандартного AGENTS.md.

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

Если my-skills.md не существует, инструмент создаст его:

Created my-skills.md

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

Found 2 skill(s)

? Select skills to sync to my-skills.md:
❯ ◉ pdf                        (project)  Comprehensive PDF manipulation toolkit...
  ◉ git-workflow                (project)  Git workflow: Best practices for commits...

<Space> Выбрать  <a> Выбрать все  <i> Инвертировать  <Enter> Подтвердить

После выбора навыков вы увидите:

✅ Synced 2 skill(s) to my-skills.md

Проверьте созданный файл

Просмотрите созданный файл:

bash

cat my-skills.md

Вы увидите:

markdown

<!-- Заголовок файла: # my-skills -->

<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...
</usage>

<available_skills>

<skill>
<name>pdf</name>
<description>Comprehensive PDF manipulation toolkit...</description>
<location>project</location>
</skill>

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

</skills_system>

Обратите внимание, что первая строка - # my-skills, это заголовок, автоматически сгенерированный инструментом на основе имени файла.

Шаг 2: Вывод во вложенный каталог

Теперь попробуйте синхронизировать навыки в несуществующий вложенный каталог:

bash

npx openskills sync -o .ruler/AGENTS.md

Почему

Некоторые инструменты (например, Windsurf) ожидают AGENTS.md в каталоге .ruler/. Если каталог не существует, инструмент автоматически создаст его.

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

Если каталог .ruler/ не существует, инструмент создаст каталог и файл:

Created .ruler/AGENTS.md

Затем запустится интерактивный интерфейс выбора (такой же, как на предыдущем шаге).

Руководство по операциям:

┌─────────────────────────────────────────────────────────────┐
│  Описание автоматического создания каталога                  │
│                                                             │
│  Введенная команда: openskills sync -o .ruler/AGENTS.md     │
│                                                             │
│  Выполнение инструмента:                                     │
│  1. Проверка существования каталога .ruler  →  Не существует│
│  2. Рекурсивное создание каталога .ruler   →  mkdir .ruler  │
│  3. Создание .ruler/AGENTS.md  →  Запись заголовка # AGENTS │
│  4. Синхронизация содержимого навыков  →  Запись списка навыков в формате XML │
│                                                             │
│  Результат: файл .ruler/AGENTS.md создан, навыки синхронизированы │
└─────────────────────────────────────────────────────────────┘

Рекурсивное создание

Инструмент рекурсивно создаст все несуществующие родительские каталоги. Например:

docs/ai/skills.md - если docs и docs/ai не существуют, оба будут созданы
.config/agents.md - будет создан скрытый каталог .config

Шаг 3: Управление несколькими файлами - настройка для разных инструментов

Предположим, вы одновременно используете Windsurf и Cursor и вам нужно настроить разные AGENTS.md для них:

bash

<!-- Настройка для Windsurf (ожидает .ruler/AGENTS.md) -->
npx openskills sync -o .ruler/AGENTS.md

<!-- Настройка для Cursor (использует AGENTS.md в корне проекта) -->
npx openskills sync

Почему

Разные инструменты могут ожидать AGENTS.md в разных местах. Используя -o, вы можете настроить правильный путь для каждого инструмента, избегая конфликтов.

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

Два файла созданы отдельно:

bash

<!-- Просмотр AGENTS.md для Windsurf -->
cat .ruler/AGENTS.md

<!-- Просмотр AGENTS.md для Cursor -->
cat AGENTS.md

Независимость файлов

Каждый файл .md независим и содержит свой собственный список навыков. Вы можете выбирать разные навыки в разных файлах:

.ruler/AGENTS.md - навыки, выбранные для Windsurf
AGENTS.md - навыки, выбранные для Cursor
docs/ai-skills.md - список навыков в документации

Шаг 4: Неинтерактивная синхронизация в пользовательский файл

В среде CI/CD вам может потребоваться пропустить интерактивный выбор и напрямую синхронизировать все навыки в пользовательский файл:

bash

npx openskills sync -o .ruler/AGENTS.md -y

Почему

Флаг -y пропускает интерактивный выбор и синхронизирует все установленные навыки. В сочетании с флагом -o, можно выводить в пользовательский путь в автоматизированном процессе.

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

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

Сценарий использования CI/CD

Использование в CI/CD скриптах:

bash

#!/bin/bash
<!-- Установка навыков -->
npx openskills install anthropics/skills -y

<!-- Синхронизация в пользовательский файл (неинтерактивно) -->
npx openskills sync -o .ruler/AGENTS.md -y

Шаг 5: Проверка выходного файла

Наконец, проверьте, правильно ли создан выходной файл:

bash

<!-- Просмотр содержимого файла -->
cat .ruler/AGENTS.md

<!-- Проверка существования файла -->
ls -l .ruler/AGENTS.md

<!-- Подтверждение количества навыков -->
grep -c "<name>" .ruler/AGENTS.md

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

Файл содержит правильный заголовок (например, # AGENTS)
Файл содержит XML-тег <skills_system>
Файл содержит список навыков <available_skills>
Каждый <skill> содержит <name>, <description>, <location>

Проверка пути вывода

Если вы не уверены в текущем рабочем каталоге, можно использовать:

bash

<!-- Просмотр текущего каталога -->
pwd

<!-- Просмотр, куда разрешается относительный путь -->
realpath .ruler/AGENTS.md

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

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

[ ] Успешно использован флаг -o для вывода в пользовательский файл
[ ] Инструмент автоматически создал несуществующий файл
[ ] Инструмент автоматически создал несуществующий вложенный каталог
[ ] Созданный файл содержит правильный заголовок (на основе имени файла)
[ ] Созданный файл содержит XML-тег <skills_system>
[ ] Созданный файл содержит полный список навыков
[ ] Можно настроить разные пути вывода для разных инструментов
[ ] Можно использовать комбинацию -y и -o в среде CI/CD

Если все вышеперечисленные пункты пройдены, поздравляем! Вы освоили метод использования пользовательского пути вывода и можете гибко синхронизировать навыки в любое место.

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

Проблема 1: Выходной файл не является markdown

Проявление:

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

Причина:

При использовании флага -o, расширение указанного файла не .md. Инструмент принудительно требует вывод в markdown-файл, чтобы AI-инструмент мог правильно разобрать его.

Решение:

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

bash

<!-- ❌ Ошибка -->
npx openskills sync -o skills.txt

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

Проблема 2: Ошибка прав на создание каталога

Проявление:

Error: EACCES: permission denied, mkdir '.ruler'

Причина:

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

Решение:

Проверьте права на родительский каталог:

bash

ls -ld .

Если прав недостаточно, обратитесь к администратору или используйте каталог с правами:

bash

<!-- Использование каталога проекта -->
cd ~/projects/my-project
npx openskills sync -o .ruler/AGENTS.md

Проблема 3: Слишком длинный путь вывода

Проявление:

Путь к файлу очень длинный, что затрудняет чтение и обслуживание команды:

bash

npx openskills sync -o docs/ai/skills/v2/internal/agents.md

Причина:

Слишком глубокая вложенность каталогов, что затрудняет управление путем.

Решение:

Используйте относительные пути (начиная с корня проекта)
Упростите структуру каталогов
Рассмотрите использование символических ссылок (см. Поддержка символических ссылок)

bash

<!-- Рекомендуемая практика: упрощение структуры каталогов -->
npx openskills sync -o docs/agents.md

Проблема 4: Забыли использовать флаг -o

Проявление:

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

Причина:

Забыли использовать флаг -o или допустили ошибку в написании.

Решение:

Проверьте, содержит ли команда -o или --output:

bash

<!-- ❌ Ошибка: забыли флаг -o -->
npx openskills sync

<!-- ✅ Правильно: использование флага -o -->
npx openskills sync -o .ruler/AGENTS.md

Используйте полную форму --output (более понятно):

bash

npx openskills sync --output .ruler/AGENTS.md

Проблема 5: Имя файла содержит специальные символы

Проявление:

Имя файла содержит пробелы или специальные символы, что приводит к ошибке разбора пути:

bash

npx openskills sync -o "my skills.md"

Причина:

Некоторые оболочки по-разному обрабатывают специальные символы, что может привести к ошибкам пути.

Решение:

Избегайте использования пробелов и специальных символов
При необходимости использования, заключайте в кавычки:

bash

<!-- Не рекомендуется -->
npx openskills sync -o "my skills.md"

<!-- Рекомендуется -->
npx openskills sync -o my-skills.md

Резюме урока

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

Использовать флаг -o или --output для синхронизации навыков в пользовательский файл .md
Механизму автоматического создания файлов и каталогов, не требующему ручной подготовки структуры каталогов
Настройке разных AGENTS.md для разных инструментов, избегая конфликтов нескольких инструментов
Техникам управления несколькими файлами, классификации и хранения списков навыков по инструментам или функциям
Использованию в среде CI/CD комбинации -y и -o для автоматической синхронизации

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

Команда	Назначение
`npx openskills sync -o custom.md`	Синхронизация в `custom.md` в корне проекта
`npx openskills sync -o .ruler/AGENTS.md`	Синхронизация в `.ruler/AGENTS.md` (автоматическое создание каталога)
`npx openskills sync -o path/to/file.md`	Синхронизация в любой путь (автоматическое создание вложенных каталогов)
`npx openskills sync -o custom.md -y`	Неинтерактивная синхронизация в пользовательский файл

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

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

Анонс следующего урока

В следующем уроке мы изучим Поддержку символических ссылок.
Вы узнаете:
Как использовать символические ссылки для обновления навыков на основе git
Преимущества и сценарии использования символических ссылок
Как управлять навыками в локальной разработке
Механизмы обнаружения и обработки символических ссылок

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

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

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

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

Функция	Путь к файлу	Номер строки
Вход точки команды sync	`src/commands/sync.ts`	18-109
Определение опций CLI	`src/cli.ts`	66
Получение пути вывода	`src/commands/sync.ts`	19
Проверка выходного файла	`src/commands/sync.ts`	22-26
Создание несуществующего файла	`src/commands/sync.ts`	28-36
Рекурсивное создание каталога	`src/commands/sync.ts`	31-32
Автоматическая генерация заголовка	`src/commands/sync.ts`	34
Интерактивная подсказка использует имя выходного файла	`src/commands/sync.ts`	70

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

syncAgentsMd(options: SyncOptions) - синхронизация навыков в указанный выходной файл
options.output - пользовательский путь вывода (опционально, по умолчанию 'AGENTS.md')

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

'AGENTS.md' - имя файла вывода по умолчанию
'.md' - принудительно требуемое расширение файла

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

Выходной файл должен заканчиваться на .md, иначе ошибка и выход (sync.ts:23-26)
Если файл не существует, автоматически создаются родительские каталоги (рекурсивно) и файл (sync.ts:28-36)
При создании файла записывается заголовок на основе имени файла: # ${outputName.replace('.md', '')} (sync.ts:34)
В интерактивной подсказке отображается имя выходного файла (sync.ts:70)
В сообщении об успешной синхронизации отображается имя выходного файла (sync.ts:105, 107)

Пользовательский путь вывода ​

Что вы сможете сделать после изучения ​

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

Когда использовать этот прием ​

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

Основная идея: гибкий контроль вывода ​

Следуйте за мной ​

Шаг 1: Базовое использование - вывод в текущий каталог ​

Шаг 2: Вывод во вложенный каталог ​

Шаг 3: Управление несколькими файлами - настройка для разных инструментов ​

Шаг 4: Неинтерактивная синхронизация в пользовательский файл ​

Шаг 5: Проверка выходного файла ​

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

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

Проблема 1: Выходной файл не является markdown ​

Проблема 2: Ошибка прав на создание каталога ​

Проблема 3: Слишком длинный путь вывода ​

Проблема 4: Забыли использовать флаг -o ​

Проблема 5: Имя файла содержит специальные символы ​

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

Анонс следующего урока ​

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

Пользовательский путь вывода

Что вы сможете сделать после изучения

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

Когда использовать этот прием

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

Основная идея: гибкий контроль вывода

Следуйте за мной

Шаг 1: Базовое использование - вывод в текущий каталог

Шаг 2: Вывод во вложенный каталог

Шаг 3: Управление несколькими файлами - настройка для разных инструментов

Шаг 4: Неинтерактивная синхронизация в пользовательский файл

Шаг 5: Проверка выходного файла

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

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

Проблема 1: Выходной файл не является markdown

Проблема 2: Ошибка прав на создание каталога

Проблема 3: Слишком длинный путь вывода

Проблема 4: Забыли использовать флаг -o

Проблема 5: Имя файла содержит специальные символы

Резюме урока

Анонс следующего урока

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