Лучшие практики разработки навыков

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

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

Написать имена навыков, соответствующие соглашению об именовании
Составлять описания, которые легко распознаются системой автоматических рекомендаций
Организовать чёткую структуру каталогов навыков
Правильно использовать функциональность скриптов
Избегать распространённых ошибок в Frontmatter
Повысить обнаруживаемость и удобство использования навыков

Зачем нужны лучшие практики

Плагин OpenCode Agent Skills не только хранит навыки, но и:

Автоматическое обнаружение: сканирует каталоги навыков из нескольких источников
Семантическое сопоставление: рекомендует навыки на основе сходства описания навыка с сообщением пользователя
Управление пространством имён: поддерживает сосуществование навыков из разных источников
Выполнение скриптов: автоматически сканирует и выполняет исполняемые скрипты

Следование лучшим практикам позволит вашим навыкам:

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

Соглашение об именовании

Правила имён навыков

Имена навыков должны соответствовать следующим правилам:

Правила именования

✅ Использовать строчные буквы, цифры и дефисы
✅ Начинать с буквы
✅ Использовать дефисы для разделения слов
❌ Не использовать заглавные буквы или символы подчёркивания
❌ Не использовать пробелы или специальные символы

Примеры:

✅ Правильные примеры	❌ Неправильные примеры	Причина
`git-helper`	`GitHelper`	Содержит заглавные буквы
`docker-build`	`docker_build`	Использует символ подчёркивания
`code-review`	`code review`	Содержит пробел
`test-utils`	`1-test`	Начинается с цифры

Основание в исходном коде: src/skills.ts:106-108

typescript

name: z.string()
  .regex(/^[\p{Ll}\p{N}-]+$/u, { message: "Name must be lowercase alphanumeric with hyphens" })
  .min(1, { message: "Name cannot be empty" }),

Связь между именем каталога и frontmatter

Имя каталога навыка и поле name в frontmatter могут отличаться:

yaml

---
# Каталог называется my-git-tools, но name в frontmatter — git-helper
name: git-helper
description: Помощник для часто используемых операций Git
---

Рекомендуемый подход:

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

Основание в исходном коде: src/skills.ts:155-158

Техники составления описания

Назначение описания

Описание навыка — это не только пояснение для пользователя, оно также используется для:

Семантическое сопоставление: плагин вычисляет сходство описания с сообщением пользователя
Рекомендация навыков: автоматически рекомендует релевантные навыки на основе сходства
Нечёткое сопоставление: при неправильном написании имени навыка используется для рекомендации похожих навыков

Хорошие описания против плохих

✅ Хорошие описания	❌ Плохие описания	Причина
"Автоматизация управления ветками Git и процесса коммитов, поддерживает автоматическую генерацию сообщений коммитов"	"Инструмент Git"	Слишком размыто, отсутствуют конкретные функции
"Генерация типобезопасного кода API-клиента для проектов Node.js"	"Полезный инструмент"	Не указан сценарий применения
"Перевод PDF на китайский язык с сохранением исходного форматирования"	"Инструмент перевода"	Не указаны особые возможности

Принципы составления описания

Конкретность: укажите конкретное назначение навыка и сценарии применения
Включение ключевых слов: включите слова, которые пользователи могут искать (например, "Git", "Docker", "перевод")
Выделение уникальной ценности: укажите преимущества этого навыка по сравнению с другими аналогичными навыками
Избегание избыточности: не повторяйте имя навыка

Пример:

markdown

---
name: pdf-translator
description: Перевод PDF-документов с английского на китайский язык, сохраняя исходное форматирование, положение изображений и структуру таблиц. Поддерживает пакетный перевод и настраиваемый глоссарий терминов.
---

Это описание включает:

✅ Конкретные функции (перевод PDF, сохранение форматирования)
✅ Сценарии применения (документы на английском языке)
✅ Уникальную ценность (сохранение форматирования, пакетная обработка, глоссарий)

Основание в исходном коде: src/skills.ts:109

typescript

description: z.string()
  .min(1, { message: "Description cannot be empty" }),

Организация каталогов

Базовая структура

Стандартный каталог навыка содержит:

my-skill/
├── SKILL.md              # Основной файл навыка (обязательный)
├── README.md             # Подробная документация (необязательно)
├── tools/                # Исполняемые скрипты (необязательно)
│   ├── setup.sh
│   └── run.sh
└── docs/                 # Поддерживающая документация (необязательно)
    ├── guide.md
    └── examples.md

Пропускаемые каталоги

Плагин автоматически пропускает следующие каталоги (не сканирует скрипты):

Автоматически пропускаемые каталоги

node_modules - зависимости Node.js
__pycache__ - кэш байт-кода Python
.git - система контроля версий Git
.venv, venv - виртуальное окружение Python
.tox, .nox - тестовое окружение Python
Любые скрытые каталоги, начинающиеся с .

Основание в исходном коде: src/skills.ts:61

typescript

const skipDirs = new Set(['node_modules', '__pycache__', '.git', '.venv', 'venv', '.tox', '.nox']);

Назначение	Рекомендуемое имя	Описание
Скрипты	`tools/` или `scripts/`	Хранение исполняемых скриптов
Документация	`docs/` или `examples/`	Хранение вспомогательной документации
Конфигурация	`config/`	Хранение файлов конфигурации
Шаблоны	`templates/`	Хранение файлов шаблонов

Использование скриптов

Правила обнаружения скриптов

Плагин автоматически сканирует исполняемые файлы в каталогах навыков:

Правила обнаружения скриптов

✅ Скрипт должен иметь права на выполнение (chmod +x script.sh)
✅ Максимальная глубина рекурсии — 10 уровней
✅ Пропуск скрытых каталогов и каталогов зависимостей
❌ Неисполняемые файлы не распознаются как скрипты

Основание в исходном коде: src/skills.ts:86

typescript

if (stats.mode & 0o111) {
  scripts.push({
    relativePath: newRelPath,
    absolutePath: fullPath
  });
}

Установка прав скриптов

Скрипты Bash:

bash

chmod +x tools/setup.sh
chmod +x tools/run.sh

Скрипты Python:

bash

chmod +x tools/scan.py

И добавьте shebang в начало файла:

python

#!/usr/bin/env python3
import sys
# ...

Пример вызова скриптов

Когда навык загружен, AI видит список доступных скриптов:

Available scripts:
- tools/setup.sh: Инициализация среды разработки
- tools/build.sh: Сборка проекта
- tools/deploy.sh: Развертывание в производственную среду

AI может вызывать эти скрипты с помощью инструмента run_skill_script:

javascript

run_skill_script({
  skill: "project-builder",
  script: "tools/build.sh",
  arguments: ["--release", "--verbose"]
})

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

Обязательные поля

name: уникальный идентификатор навыка

Строчные буквы, цифры и дефисы
Короткий, но описательный
Избегайте общих имён (например, helper, tool)

description: описание навыка

Укажите конкретные функции
Включите сценарии применения
Умеренная длина (1-2 предложения)

Необязательные поля

license: информация о лицензии

yaml

license: MIT

allowed-tools: ограничение инструментов, которые может использовать навык

yaml

allowed-tools:
  - read
  - write
  - bash

metadata: пользовательские метаданные

yaml

metadata:
  author: "Your Name"
  version: "1.0.0"
  category: "development"

Основание в исходном коде: src/skills.ts:105-114

typescript

const SkillFrontmatterSchema = z.object({
  name: z.string()
    .regex(/^[\p{Ll}\p{N}-]+$/u, { message: "Name must be lowercase alphanumeric with hyphens" })
    .min(1, { message: "Name cannot be empty" }),
  description: z.string()
    .min(1, { message: "Description cannot be empty" }),
  license: z.string().optional(),
  "allowed-tools": z.array(z.string()).optional(),
  metadata: z.record(z.string(), z.string()).optional()
});

Полный пример

markdown

---
name: docker-deploy
description: Автоматизация процесса сборки и развертывания Docker-образов, поддержка конфигурации для нескольких сред, проверок работоспособности и отката
license: MIT
allowed-tools:
  - read
  - write
  - bash
metadata:
  version: "2.1.0"
  author: "DevOps Team"
  category: "deployment"
---

# Автоматическое развертывание Docker

Этот навык помогает автоматизировать процесс сборки, отправки и развертывания Docker-образов.

## Использование

...

Избегание распространённых ошибок

Ошибка 1: Имя не соответствует стандарту

Неправильный пример:

yaml

name: MyAwesomeSkill  # ❌ Заглавные буквы

Исправление:

yaml

name: my-awesome-skill  # ✅ Строчные буквы + дефисы

Ошибка 2: Описание слишком размытое

Неправильный пример:

yaml

description: "Полезный инструмент"  # ❌ Слишком размыто

Исправление:

yaml

description: "Автоматизация процесса коммитов Git, автоматическая генерация сообщений коммитов, соответствующих стандартам"  # ✅ Конкретно и ясно

Ошибка 3: Скрипт без прав на выполнение

Проблема: скрипт не распознаётся как исполняемый

Решение:

bash

chmod +x tools/setup.sh

Проверка:

bash

ls -l tools/setup.sh
# Должно отображать: -rwxr-xr-x (есть права x)

Ошибка 4: Конфликт имён каталогов

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

Решения:

Используйте пространства имён (через конфигурацию плагина или структуру каталогов)
Или используйте более описательные имена

Основание в исходном коде: src/skills.ts:258-259

typescript

// Навыки с одинаковыми именами: сохраняется только первый, последующие игнорируются
if (skillsByName.has(skill.name)) {
  continue;
}

Повышение обнаруживаемости

1. Оптимизация ключевых слов в описании

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

yaml

---
name: code-reviewer
description: Инструмент автоматического анализа кода, проверка качества кода, потенциальных ошибок, уязвимостей безопасности и проблем производительности. Поддержка JavaScript, TypeScript, Python и других языков.
---

Ключевые слова: анализ кода, качество кода, ошибки, уязвимости безопасности, проблемы производительности, JavaScript, TypeScript, Python

2. Использование стандартных расположений навыков

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

.opencode/skills/ - на уровне проекта (наивысший приоритет)
.claude/skills/ - Claude на уровне проекта
~/.config/opencode/skills/ - на уровне пользователя
~/.claude/skills/ - Claude на уровне пользователя

Рекомендуемый подход:

Навыки, специфичные для проекта → размещайте на уровне проекта
Общие навыки → размещайте на уровне пользователя

3. Предоставление подробной документации

Помимо SKILL.md, вы также можете предоставить:

README.md - подробное описание и примеры использования
docs/guide.md - полное руководство по использованию
docs/examples.md - практические примеры

Итоги урока

Этот урок представил лучшие практики разработки навыков:

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

Следование этим лучшим практикам позволит вашим навыкам:

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

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

В следующем уроке мы изучим Справочник по API.
Вы узнаете:
Подробное описание параметров всех доступных инструментов
Примеры вызова инструментов и формат возвращаемых значений
Расширенное использование и важные замечания

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

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

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

Функция	Путь к файлу	Номера строк
Проверка имени навыка	`src/skills.ts`	106-108
Проверка описания навыка	`src/skills.ts`	109-110
Определение схемы Frontmatter	`src/skills.ts`	105-114
Список пропускаемых каталогов	`src/skills.ts`	61
Проверка прав на выполнение скриптов	`src/skills.ts`	86
Логика удаления дубликатов навыков с одинаковыми именами	`src/skills.ts`	258-259

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

Пропускаемые каталоги: ['node_modules', '__pycache__', '.git', '.venv', 'venv', '.tox', '.nox']

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

findScripts(skillPath: string, maxDepth: number = 10): рекурсивный поиск исполняемых скриптов в каталоге навыка
parseSkillFile(skillPath: string): парсинг SKILL.md и проверка frontmatter

Лучшие практики разработки навыков ​

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

Зачем нужны лучшие практики ​

Соглашение об именовании ​

Правила имён навыков ​

Связь между именем каталога и frontmatter ​

Техники составления описания ​

Назначение описания ​

Хорошие описания против плохих ​

Принципы составления описания ​

Организация каталогов ​

Базовая структура ​

Пропускаемые каталоги ​

Рекомендуемые имена каталогов ​

Использование скриптов ​

Правила обнаружения скриптов ​

Установка прав скриптов ​

Пример вызова скриптов ​

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

Обязательные поля ​

Необязательные поля ​

Полный пример ​

Избегание распространённых ошибок ​

Ошибка 1: Имя не соответствует стандарту ​

Ошибка 2: Описание слишком размытое ​

Ошибка 3: Скрипт без прав на выполнение ​

Ошибка 4: Конфликт имён каталогов ​

Повышение обнаруживаемости ​

1. Оптимизация ключевых слов в описании ​

2. Использование стандартных расположений навыков ​

3. Предоставление подробной документации ​

Итоги урока ​

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

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

Лучшие практики разработки навыков

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

Зачем нужны лучшие практики

Соглашение об именовании

Правила имён навыков

Связь между именем каталога и frontmatter

Техники составления описания

Назначение описания

Хорошие описания против плохих

Принципы составления описания

Организация каталогов

Базовая структура

Пропускаемые каталоги

Рекомендуемые имена каталогов

Использование скриптов

Правила обнаружения скриптов

Установка прав скриптов

Пример вызова скриптов

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

Обязательные поля

Необязательные поля

Полный пример

Избегание распространённых ошибок

Ошибка 1: Имя не соответствует стандарту

Ошибка 2: Описание слишком размытое

Ошибка 3: Скрипт без прав на выполнение

Ошибка 4: Конфликт имён каталогов

Повышение обнаруживаемости

1. Оптимизация ключевых слов в описании

2. Использование стандартных расположений навыков

3. Предоставление подробной документации

Итоги урока

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

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