Лучшие практики

Чему вы научитесь

После прохождения этого урока вы сможете:

Выбирать подходящий метод установки навыков в зависимости от потребностей проекта (локально в проекте, глобально или Universal)
Создавать файлы SKILL.md, соответствующие стандартам (именование, описание, инструкции)
Использовать символические ссылки для эффективной локальной разработки
Управлять версиями и обновлениями навыков
Совместно работать над навыками в командной среде
Интегрировать OpenSkills в рабочие процессы CI/CD

Текущие проблемы

Вы научились устанавливать и использовать навыки, но в реальных проектах сталкиваетесь с такими проблемами:

Навыки следует устанавливать в каталоге проекта или глобально?
Как несколько AI-агентов могут совместно использовать навыки?
Вы пишете навыки много раз, но AI всё равно их не запоминает
Члены команды устанавливают навыки по отдельности, что приводит к несоответствию версий
После каждого локального изменения навыка приходится переустанавливать его, что утомительно

В этом уроке мы обобщим лучшие практики OpenSkills, которые помогут вам решить эти проблемы.

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

Оптимизация конфигурации проекта: выбор подходящего места установки навыков в зависимости от типа проекта
Мультиагентные среды: одновременное использование Claude Code, Cursor, Windsurf и других инструментов
Стандартизация навыков: единые форматы навыков и стандарты написания для команд
Локальная разработка: быстрая итерация и тестирование навыков
Командная работа: совместное использование навыков, контроль версий, интеграция CI/CD

🎒 Предварительные требования

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

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

✅ Завершили Быстрый старт
✅ Установили хотя бы один навык и синхронизировали его с AGENTS.md
✅ Понимаете базовый формат SKILL.md

Лучшие практики конфигурации проекта

1. Локальная vs глобальная vs Universal установка

Выбор подходящего места установки — первый шаг в конфигурации проекта.

Локальная установка в проекте (по умолчанию)

Сценарий использования: навыки, специфичные для конкретного проекта

bash

# Установка в .claude/skills/
npx openskills install anthropics/skills

Преимущества:

✅ Навыки контролируются версиями вместе с проектом
✅ Разные проекты могут использовать разные версии навыков
✅ Не требуется глобальная установка, снижаются зависимости

Рекомендуется для:

Специфичных для проекта навыков (например, процессы сборки для конкретных фреймворков)
Внутренних бизнес-навыков, разработанных командой
Навыков, зависящих от конфигурации проекта

Глобальная установка

Сценарий использования: навыки, общие для всех проектов

bash

# Установка в ~/.claude/skills/
npx openskills install anthropics/skills --global

Преимущества:

✅ Все проекты используют один и тот же набор навыков
✅ Не нужно устанавливать повторно для каждого проекта
✅ Централизованное управление обновлениями

Рекомендуется для:

Официальной библиотеки навыков Anthropic (anthropics/skills)
Универсальных утилитарных навыков (например, обработка PDF, операции с Git)
Личных часто используемых навыков

Режим Universal (мультиагентные среды)

Сценарий использования: одновременное использование нескольких AI-агентов

bash

# Установка в .agent/skills/
npx openskills install anthropics/skills --universal

Приоритет поиска (от высшего к низшему):

./.agent/skills/ (Universal локально в проекте)
~/.agent/skills/ (Universal глобально)
./.claude/skills/ (Claude Code локально в проекте)
~/.claude/skills/ (Claude Code глобально)

Рекомендуется для:

✅ Использования при работе с несколькими агентами (Claude Code + Cursor + Windsurf)
✅ Избежания конфликтов с Claude Code Marketplace
✅ Единого управления навыками для всех агентов

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

Если ваш AGENTS.md используется совместно Claude Code и другими агентами, используйте --universal, чтобы избежать конфликтов навыков. Режим Universal использует каталог .agent/skills/, который изолирован от .claude/skills/ Claude Code.

2. Предпочитайте npx вместо глобальной установки

OpenSkills разработан для использования по требованию, поэтому всегда используйте npx:

bash

# ✅ Рекомендуется: использовать npx
npx openskills install anthropics/skills
npx openskills sync
npx openskills list

# ❌ Избегайте: прямой вызов после глобальной установки
openskills install anthropics/skills

Преимущества:

✅ Не требуется глобальная установка, избегание конфликтов версий
✅ Всегда используется последняя версия (npx автоматически обновляется)
✅ Снижаются системные зависимости

Когда нужна глобальная установка:

В средах CI/CD (для производительности)
При частых вызовах в скриптах (сокращение времени запуска npx)

bash

# Глобальная установка в CI/CD или скриптах
npm install -g openskills
openskills install anthropics/skills -y
openskills sync -y

Лучшие практики управления навыками

1. Стандарты написания SKILL.md

Соглашение об именовании: используйте формат с дефисами

Правила:

✅ Правильно: pdf-editor, api-client, git-workflow
❌ Неправильно: PDF Editor (пробелы), pdf_editor (подчёркивания), PdfEditor (camelCase)

Причина: формат с дефисами является URL-дружественным идентификатором, соответствующим соглашениям об именовании репозиториев GitHub и файловых систем.

Написание описания: третье лицо, 1-2 предложения

Правила:

✅ Правильно: Use this skill for comprehensive PDF manipulation.
❌ Неправильно: You should use this skill to manipulate PDFs. (второе лицо)

Сравнение примеров:

Сценарий	❌ Неправильно (второе лицо)	✅ Правильно (третье лицо)
PDF навык	You can use this to extract text from PDFs.	Extract text from PDFs with this skill.
Git навык	When you need to manage branches, use this.	Manage Git branches with this skill.
API навык	If you want to call the API, load this skill.	Call external APIs with this skill.

Написание инструкций: форма Imperative/Infinitive

Правила:

✅ Правильно: "To accomplish X, execute Y"
✅ Правильно: "Load this skill when Z"
❌ Неправильно: "You should do X"
❌ Неправильно: "If you need Y"

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

Начинайте с глагола: "Create" → "Use" → "Return"
Опускайте "You": не говорите "You should"
Указывайте пути явно: ссылки на ресурсы с префиксом references/

Сравнение примеров:

❌ Неправильное написание	✅ Правильное написание
"You should create a file"	"Create a file"
"When you want to load this skill"	"Load this skill when"
"If you need to see the docs"	"See references/guide.md"

Почему использовать Imperative/Infinitive?

Этот стиль написания облегчает AI-агентам разбор и выполнение инструкций. Формы Imperative и Infinitive устраняют субъект "you", делая инструкции более прямыми и чёткими.

2. Контроль размера файла

Размер файла SKILL.md:

✅ Рекомендуется: менее 5 000 слов
⚠️ Предупреждение: более 8 000 слов может вызвать переполнение контекста
❌ Запрещено: более 10 000 слов

Метод контроля:

Переместите подробную документацию в каталог references/:

markdown

# SKILL.md (основные инструкции)

## Instructions

To process data:

1. Call the API endpoint
2. See `references/api-docs.md` for detailed response format # Подробная документация
3. Process the result

## Bundled Resources

For detailed API documentation, see:
- `references/api-docs.md` # Не загружается в контекст, экономит токены
- `references/examples.md`

Сравнение размеров файлов:

Файл	Ограничение размера	Загружается в контекст?
`SKILL.md`	< 5 000 слов	✅ Да
`references/`	Без ограничений	❌ Нет (загружается по требованию)
`scripts/`	Без ограничений	❌ Нет (исполняемый)
`assets/`	Без ограничений	❌ Нет (файлы шаблонов)

3. Приоритет поиска навыков

OpenSkills ищет навыки в следующем порядке приоритета (от высшего к низшему):

1. ./.agent/skills/ # Universal локально в проекте
2. ~/.agent/skills/ # Universal глобально
3. ./.claude/skills/ # Claude Code локально в проекте
4. ~/.claude/skills/ # Claude Code глобально

Механизм дедупликации:

Возвращается только первый найденный навык с совпадающим именем
Локальные навыки проекта имеют приоритет над глобальными

Пример сценария:

Проект A:
- .claude/skills/pdf # Локальная версия проекта v1.0
- ~/.claude/skills/pdf # Глобальная версия v2.0

# openskills read pdf загрузит .claude/skills/pdf (v1.0)

Рекомендации:

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

Лучшие практики локальной разработки

1. Использование символических ссылок для итеративной разработки

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

Решение: использование символических ссылок (symlink)

bash

# 1. Клонирование репозитория навыков в каталог разработки
git clone [email protected]:your-org/my-skills.git ~/dev/my-skills

# 2. Создание каталога навыков
mkdir -p .claude/skills

# 3. Создание символической ссылки
ln -s ~/dev/my-skills/my-skill .claude/skills/my-skill

# 4. Синхронизация с AGENTS.md
npx openskills sync

Преимущества:

✅ Изменения в исходных файлах вступают в силу немедленно (переустановка не требуется)
✅ Поддержка обновлений на основе Git (просто pull)
✅ Несколько проектов могут совместно использовать одну и ту же версию навыка в разработке

Проверка символической ссылки:

bash

# Просмотр символической ссылки
ls -la .claude/skills/

# Пример вывода:
# my-skill -> /Users/yourname/dev/my-skills/my-skill

Примечания:

✅ Символические ссылки распознаются командой openskills list
✅ Сломанные символические ссылки автоматически пропускаются (без сбоев)
⚠️ Пользователям Windows необходимо использовать Git Bash или WSL (Windows нативно не поддерживает символические ссылки)

2. Совместное использование навыков в нескольких проектах

Сценарий: несколько проектов должны использовать один и тот же набор командных навыков.

Метод 1: глобальная установка

bash

# Глобальная установка репозитория командных навыков
npx openskills install your-org/team-skills --global

Метод 2: символическая ссылка на каталог разработки

bash

# Создание символических ссылок в каждом проекте
ln -s ~/dev/team-skills/my-skill .claude/skills/my-skill

Метод 3: Git Submodule

bash

# Добавление репозитория навыков как подмодуля
git submodule add [email protected]:your-org/team-skills.git .claude/skills

# Обновление подмодуля
git submodule update --init --recursive

Рекомендуемый выбор:

Метод	Сценарий использования	Преимущества	Недостатки
Глобальная установка	Все проекты используют единые навыки	Централизованное управление, лёгкие обновления	Невозможна настройка для каждого проекта
Символическая ссылка	Локальная разработка и тестирование	Изменения вступают в силу немедленно	Требуется ручное создание ссылок
Git Submodule	Командная работа, контроль версий	Контроль версий вместе с проектом	Сложное управление подмодулями

Лучшие практики командной работы

1. Контроль версий навыков

Лучшая практика: независимый контроль версий для репозитория навыков

bash

# Структура репозитория командных навыков
team-skills/
├── .git/
├── pdf-editor/
│   └── SKILL.md
├── api-client/
│   └── SKILL.md
└── git-workflow/
    └── SKILL.md

Метод установки:

bash

# Установка навыков из командного репозитория
npx openskills install [email protected]:your-org/team-skills.git

Рабочий процесс обновления:

bash

# Обновление всех навыков
npx openskills update

# Обновление конкретных навыков
npx openskills update pdf-editor,api-client

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

Используйте Git Tags для маркировки стабильных версий: v1.0.0, v1.1.0
Записывайте версию навыка в AGENTS.md: <skill name="pdf-editor" version="1.0.0">
Используйте фиксированные стабильные версии в CI/CD

2. Соглашения об именовании навыков

Единые командные соглашения об именовании:

Тип навыка	Шаблон именования	Примеры
Общие инструменты	`<tool-name>`	`pdf`, `git`, `docker`
Связанные с фреймворком	`<framework>-<purpose>`	`react-component`, `django-model`
Рабочие процессы	`<workflow>`	`ci-cd`, `code-review`
Командные	`<team>-<purpose>`	`team-api`, `company-deploy`

Примеры:

bash

# ✅ Единое именование
team-skills/
├── pdf/ # Обработка PDF
├── git-workflow/ # Рабочий процесс Git
├── react-component/ # Генерация компонентов React
└── team-api/ # Командной API клиент

3. Стандарты документации навыков

Единая структура командной документации:

markdown

---
name: <skill-name>
description: <1-2 предложения, третье лицо>
author: <команда/автор>
version: <номер версии>
---

# <Название навыка>

## When to Use

Load this skill when:
- Сценарий 1
- Сценарий 2

## Instructions

To accomplish task:

1. Шаг 1
2. Шаг 2

## Bundled Resources

For detailed information:
- `references/api-docs.md`
- `scripts/helper.py`

Контрольный список:

[ ] name использует формат с дефисами
[ ] description составляет 1-2 предложения в третьем лице
[ ] Инструкции используют форму imperative/infinitive
[ ] Включены поля author и version (командной стандарт)
[ ] Подробное описание When to Use

Лучшие практики интеграции CI/CD

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

Сценарий: автоматизация управления навыками в средах CI/CD

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

bash

# Пример скрипта CI/CD
#!/bin/bash

# Установка навыков (неинтерактивно)
npx openskills install anthropics/skills -y
npx openskills install [email protected]:your-org/team-skills.git -y

# Синхронизация с AGENTS.md (неинтерактивно)
npx openskills sync -y

Пример GitHub Actions:

yaml

name: Setup Skills

on: [push]

jobs:
  setup:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4

    - name: Install Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '20'

    - name: Install OpenSkills
      run: npx openskills install anthropics/skills -y

    - name: Sync to AGENTS.md
      run: npx openskills sync -y

    - name: Verify Skills
      run: npx openskills list

2. Автоматизация обновления навыков

Запланированное обновление навыков:

yaml

# .github/workflows/update-skills.yml
name: Update Skills

on:
  schedule:
  - cron: '0 0 * * 0' # Обновление каждое воскресенье
  workflow_dispatch:

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4

    - name: Update Skills
      run: npx openskills update -y

    - name: Sync to AGENTS.md
      run: npx openskills sync -y

    - name: Commit Changes
      run: |
        git config --local user.email "[email protected]"
        git config --local user.name "GitHub Action"
        git add AGENTS.md
        git diff --staged --quiet || git commit -m "Update skills"
        git push

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

Сценарий: синхронизация навыков в пользовательский файл (например, .ruler/AGENTS.md)

bash

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

Пример CI/CD:

yaml

# Генерация разных AGENTS.md для разных AI-агентов
- name: Sync for Claude Code
  run: npx openskills sync -o AGENTS.md -y

- name: Sync for Cursor
  run: npx openskills sync -o .cursor/AGENTS.md -y

- name: Sync for Windsurf
  run: npx openskills sync -o .windsurf/AGENTS.md -y

Распространённые проблемы и решения

Проблема 1: Навык не найден

Симптомы:

bash

npx openskills read my-skill
# Error: Skill not found: my-skill

Шаги по устранению неполадок:

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

bash

npx openskills list

Проверьте, правильно ли указано имя навыка (с учётом регистра):

bash

# ❌ Неправильно
npx openskills read My-Skill

# ✅ Правильно
npx openskills read my-skill

Проверьте, не переопределяется ли навык в каталоге с более высоким приоритетом:

bash

# Просмотр местоположений навыков
ls -la .claude/skills/my-skill
ls -la ~/.claude/skills/my-skill

Проблема 2: Символическая ссылка недоступна

Симптомы:

bash

ln -s ~/dev/my-skills/my-skill .claude/skills/my-skill
# ln: failed to create symbolic link: Operation not permitted

Решения:

macOS: разрешите символические ссылки в Системных настройках
Windows: используйте Git Bash или WSL (Windows нативно не поддерживает символические ссылки)
Linux: проверьте права доступа к файловой системе

Проблема 3: Обновление навыка не вступает в силу

Симптомы:

bash

npx openskills update
# ✅ Skills updated successfully

npx openskills read my-skill
# Содержимое всё ещё старой версии

Причина: AI-агент закэшировал старое содержимое навыка.

Решения:

Повторно синхронизируйте AGENTS.md:

bash

npx openskills sync

Проверьте временную метку файла навыка:

bash

ls -la .claude/skills/my-skill/SKILL.md

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

bash

npx openskills read my-skill

Резюме урока

Ключевые моменты лучших практик OpenSkills:

Конфигурация проекта

✅ Локальная установка в проекте: навыки, специфичные для проекта
✅ Глобальная установка: навыки, общие для всех проектов
✅ Режим Universal: совместное использование навыков в мультиагентных средах
✅ Предпочитайте npx вместо глобальной установки

Управление навыками

✅ Стандарты написания SKILL.md: именование с дефисами, описания в третьем лице, инструкции в форме imperative
✅ Контроль размера файла: SKILL.md < 5 000 слов, подробная документация в references/
✅ Приоритет поиска навыков: понимание приоритета и дедупликации 4 каталогов

Локальная разработка

✅ Использование символических ссылок для итеративной разработки
✅ Совместное использование навыков в нескольких проектах: глобальная установка, символические ссылки, Git Submodule

Командная работа

✅ Контроль версий навыков: независимые репозитории, Git Tags
✅ Единые соглашения об именовании: инструменты, фреймворки, рабочие процессы
✅ Единые стандарты документации: author, version, When to Use

Интеграция CI/CD

✅ Неинтерактивная установка и синхронизация: флаг -y
✅ Автоматизация обновлений: запланированные задачи, workflow_dispatch
✅ Пользовательский путь вывода: флаг -o

Следующий урок

В следующем уроке мы изучим FAQ.
Вы узнаете:
Быстрые ответы на распространённые вопросы по OpenSkills
Методы устранения неполадок при сбоях установки, не загружающихся навыках и т.д.
Советы по конфигурации для совместной работы с Claude Code

Приложение: ссылки на исходный код

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

Обновлено: 2026-01-24

Функция	Путь к файлу	Номера строк
Приоритет поиска навыков	`src/utils/dirs.ts`	14-25
Механизм дедупликации навыков	`src/utils/skills.ts`	42-43, 57
Обработка символических ссылок	`src/utils/skills.ts`	10-25
Извлечение полей YAML	`src/utils/yaml.ts`	4-7
Защита от обхода путей	`src/commands/install.ts`	71-78
Неинтерактивная установка	`src/commands/install.ts`	424
Пользовательский путь вывода	`src/commands/sync.ts`	19-36

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

4 каталога поиска навыков: ./.agent/skills/, ~/.agent/skills/, ./.claude/skills/, ~/.claude/skills/

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

getSearchDirs(): string[] - возвращает каталоги поиска навыков, отсортированные по приоритету
isDirectoryOrSymlinkToDirectory(entry: Dirent, parentDir: string): boolean - проверяет, является ли каталогом или символическая ссылка указывает на каталог
extractYamlField(content: string, field: string): string - извлекает значение поля YAML (неголодное совпадение)
isPathInside(path: string, targetDir: string): boolean - проверяет, находится ли путь внутри целевого каталога (предотвращает обход путей)

Примеры файлов навыков:

examples/my-first-skill/SKILL.md - пример минимальной структуры
examples/my-first-skill/references/skill-format.md - справочник по спецификации формата

Лучшие практики ​

Чему вы научитесь ​

Текущие проблемы ​

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

🎒 Предварительные требования ​

Лучшие практики конфигурации проекта ​

1. Локальная vs глобальная vs Universal установка ​

Локальная установка в проекте (по умолчанию) ​

Глобальная установка ​

Режим Universal (мультиагентные среды) ​

2. Предпочитайте npx вместо глобальной установки ​

Лучшие практики управления навыками ​

1. Стандарты написания SKILL.md ​

Соглашение об именовании: используйте формат с дефисами ​

Написание описания: третье лицо, 1-2 предложения ​

Написание инструкций: форма Imperative/Infinitive ​

2. Контроль размера файла ​

3. Приоритет поиска навыков ​

Лучшие практики локальной разработки ​

1. Использование символических ссылок для итеративной разработки ​

2. Совместное использование навыков в нескольких проектах ​

Лучшие практики командной работы ​

1. Контроль версий навыков ​

2. Соглашения об именовании навыков ​

3. Стандарты документации навыков ​

Лучшие практики интеграции CI/CD ​

1. Неинтерактивная установка и синхронизация ​

2. Автоматизация обновления навыков ​

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

Распространённые проблемы и решения ​

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

Проблема 2: Символическая ссылка недоступна ​

Проблема 3: Обновление навыка не вступает в силу ​

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

Конфигурация проекта ​

Управление навыками ​

Локальная разработка ​

Командная работа ​

Интеграция CI/CD ​

Следующий урок ​

Приложение: ссылки на исходный код ​

Лучшие практики

Чему вы научитесь

Текущие проблемы

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

🎒 Предварительные требования

Лучшие практики конфигурации проекта

1. Локальная vs глобальная vs Universal установка

Локальная установка в проекте (по умолчанию)

Глобальная установка

Режим Universal (мультиагентные среды)

2. Предпочитайте npx вместо глобальной установки

Лучшие практики управления навыками

1. Стандарты написания SKILL.md

Соглашение об именовании: используйте формат с дефисами

Написание описания: третье лицо, 1-2 предложения

Написание инструкций: форма Imperative/Infinitive

2. Контроль размера файла

3. Приоритет поиска навыков

Лучшие практики локальной разработки

1. Использование символических ссылок для итеративной разработки

2. Совместное использование навыков в нескольких проектах

Лучшие практики командной работы

1. Контроль версий навыков

2. Соглашения об именовании навыков

3. Стандарты документации навыков

Лучшие практики интеграции CI/CD

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

2. Автоматизация обновления навыков

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

Распространённые проблемы и решения

Проблема 1: Навык не найден

Проблема 2: Символическая ссылка недоступна

Проблема 3: Обновление навыка не вступает в силу

Резюме урока

Конфигурация проекта

Управление навыками

Локальная разработка

Командная работа

Интеграция CI/CD

Следующий урок

Приложение: ссылки на исходный код