Создание пользовательских навыков

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

Создавать с нуля полный файл навыка SKILL.md
Писать YAML frontmatter, соответствующий стандартам Anthropic
Проектировать разумную структуру каталогов навыков (references/, scripts/, assets/)
Использовать символические ссылки для локальной разработки и итераций
Устанавливать и проверять пользовательские навыки с помощью команды openskills

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

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

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

Инкапсуляция рабочих процессов: Запишите повторяющиеся шаги операций в виде навыков, чтобы ИИ выполнял их полностью за один раз
Накопление знаний команды: Упакуйте внутренние стандарты команды, документацию API, скрипты в навыки для обмена со всеми участниками
Интеграция инструментов: Создайте специализированные навыки для конкретных инструментов (обработка PDF, очистка данных, процессы развёртывания)
Локальная разработка: В процессе разработки вносите изменения в навыки и тестируйте их без повторной установки

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

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

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

✅ Установлен OpenSkills
✅ Установлен и синхронизирован хотя бы один навык (понимаете базовый процесс)
✅ Знакомы с базовым синтаксисом Markdown

Основная идея

Что такое SKILL.md?

SKILL.md — это стандартный формат системы навыков Anthropic, который использует YAML frontmatter для описания метаданных навыка и Markdown для предоставления инструкций по выполнению. Он имеет три ключевых преимущества:

Единый формат — Все агенты (Claude Code, Cursor, Windsurf и др.) используют одинаковое описание навыков
Постепенная загрузка — Полное содержимое загружается только при необходимости, сохраняя краткость контекста ИИ
Возможность упаковки ресурсов — Поддержка трёх типов дополнительных ресурсов: references/, scripts/, assets/

Минимальная vs полная структура

Минимальная структура (подходит для простых навыков):

my-skill/
└── SKILL.md          # Только один файл

Полная структура (подходит для сложных навыков):

my-skill/
├── SKILL.md          # Основные инструкции (< 5000 слов)
├── references/       # Подробная документация (загружается по запросу)
│   └── api-docs.md
├── scripts/          # Исполняемые скрипты
│   └── helper.py
└── assets/           # Шаблоны и выходные файлы
    └── template.json

Когда использовать полную структуру?

references/: Когда документация API, схемы баз данных, подробные руководства превышают 5000 слов
scripts/: Когда необходимо выполнять детерминированные, повторяющиеся задачи (преобразование данных, форматирование)
assets/: Когда нужны выходные шаблоны, изображения, шаблонный код

Пошаговое руководство

Шаг 1: Создание каталога навыка

Почему: Создайте отдельный каталог для организации файлов навыка

bash

mkdir my-skill
cd my-skill

Вы должны увидеть: Текущий каталог пуст

Шаг 2: Написание основной структуры SKILL.md

Почему: SKILL.md должен начинаться с YAML frontmatter, определяющего метаданные навыка

Создайте файл SKILL.md:

markdown

---
name: my-skill                    # Обязательное: идентификатор в формате дефисов
description: When to use this skill.  # Обязательное: 1-2 предложения, третье лицо
---

# Заголовок навыка

Подробное описание навыка.

Точки проверки:

✅ Первая строка — ---
✅ Содержит поле name (формат дефисов, например pdf-editor, api-client)
✅ Содержит поле description (1-2 предложения, третье лицо)
✅ После завершения YAML снова используется ---

Типичные ошибки

Ошибочный пример	Метод исправления
`name: My Skill` (пробелы)	Изменить на `name: my-skill` (дефисы)
`description: You should use this for...` (второе лицо)	Изменить на `description: Use this skill for...` (третье лицо)
---	---
`description` слишком длинный (более 100 слов)	Сократить до 1-2 предложений с кратким описанием

Шаг 3: Написание инструкций

Почему: Инструкции говорят ИИ-агенту, как выполнять задачу, должны использовать форму imperative/infinitive

Продолжите редактировать SKILL.md:

markdown

---
name: my-skill
description: Use this skill to demonstrate how to write proper instructions.
---

# My Skill

## When to Use

Load this skill when:
- Demonstrating instruction writing patterns
- Understanding imperative/infinitive form
- Learning SKILL.md format

## Instructions

To execute this skill:

1. Read the user's input
2. Process the data
3. Return the result

For detailed information, see references/guide.md

Стиль написания:

✅ Правильный стиль (imperative/infinitive)	❌ Неправильный стиль (второе лицо)
"To accomplish X, execute Y"	"You should do X"
"Load this skill when Z"	"If you need Y"
"See references/guide.md"	"When you want Z"

Памятка

Три принципа написания инструкций:

Глагол в начале: "Create" → "Use" → "Return"
Опустить "You": Не говорить "You should"
Явный путь: Ссылки на ресурсы начинаются с references/

Шаг 4: Добавление упакованных ресурсов (необязательно)

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

4.1 Добавление references/

bash

mkdir references

Создайте references/api-docs.md:

markdown

# API Documentation

## Overview

This section provides detailed API information...

## Endpoints

### GET /api/data

Returns processed data.

Response:
```json
{
  "status": "success",
  "data": [...]
}


Ссылка в `SKILL.md`:

```markdown
## Instructions

To fetch data:

1. Call the API endpoint
2. See `references/api-docs.md` for detailed response format
3. Process the result

4.2 Добавление scripts/

bash

mkdir scripts

Создайте scripts/process.py:

python

#!/usr/bin/env python3
import sys

def main():
    # Processing logic
    print("Processing complete")

if __name__ == "__main__":
    main()

Ссылка в SKILL.md:

markdown

## Instructions

To process data:

1. Execute the script:
   ```bash
   python scripts/process.py

Review the output


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

- **Не загружается в контекст**: Экономит токены, подходит для больших файлов
- **Может выполняться независимо**: ИИ-агент может вызывать напрямую без предварительной загрузки содержимого
- **Подходит для детерминированных задач**: Преобразование данных, форматирование, генерация и т.д.

:::

#### 4.3 Добавление assets/

```bash
mkdir assets

Добавьте файл шаблона assets/template.json:

json

{
  "title": "{{ title }}",
  "content": "{{ content }}"
}

Ссылка в SKILL.md:

markdown

## Instructions

To generate output:

1. Load the template: `assets/template.json`
2. Replace placeholders with actual data
3. Write to output file

Шаг 5: Проверка формата SKILL.md

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

bash

npx openskills install ./my-skill

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

✔ Found skill: my-skill
  Description: Use this skill to demonstrate how to write proper instructions.
  Size: 1.2 KB

? Select skills to install: (Use arrow keys)
❯ ☑ my-skill

Выберите навык и нажмите Enter, должны увидеть:

✔ Installing my-skill...
✔ Skill installed successfully to .claude/skills/my-skill

Next steps:
  Run: npx openskills sync
  Then: Ask your AI agent to use the skill

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

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

[ ] SKILL.md начинается с ---
[ ] Содержит поля name и description
[ ] name использует формат дефисов (my-skill, а не my_skill)
[ ] description — это краткое описание из 1-2 предложений
[ ] Инструкции используют форму imperative/infinitive
[ ] Все пути ссылок references/, scripts/, assets/ правильные

Шаг 6: Синхронизация с AGENTS.md

Почему: Чтобы ИИ-агент знал, что этот навык доступен

bash

npx openskills sync

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

✔ Found 1 skill:
  ☑ my-skill

✔ Syncing to AGENTS.md...
✔ Updated AGENTS.md successfully

Проверьте созданный AGENTS.md:

markdown

<!-- SKILLS_SYSTEM_START -->
...
<available_skills>
  <skill name="my-skill">Use this skill to demonstrate how to write proper instructions.</skill>
</available_skills>
...
<!-- SKILLS_SYSTEM_END -->

Шаг 7: Проверка загрузки навыка

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

bash

npx openskills read my-skill

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

Loading skill: my-skill
Base directory: /path/to/project/.claude/skills/my-skill

---
name: my-skill
description: Use this skill to demonstrate how to write proper instructions.
---

# My Skill
... (полное содержимое SKILL.md)

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

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

✅ Создали каталог навыка с SKILL.md
✅ SKILL.md содержит правильный YAML frontmatter и содержимое Markdown
✅ Навык успешно установлен в .claude/skills/
✅ Навык синхронизирован с AGENTS.md
✅ С помощью openskills read можно загрузить содержимое навыка

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

Проблема 1: При установке выводится "Invalid SKILL.md (missing YAML frontmatter)"

Причина: SKILL.md не начинается с ---

Решение: Проверьте, является ли первая строка файла ---, а не # My Skill или другим содержимым

Проблема 2: ИИ-агент не распознаёт навык

Причина: Не выполнена команда openskills sync или AGENTS.md не обновлён

Решение: Запустите npx openskills sync и проверьте, содержит ли AGENTS.md запись о навыке

Проблема 3: Ошибка разрешения пути к ресурсам

Причина: В SKILL.md используются абсолютные пути или неправильные относительные пути

Решение:

✅ Правильно: references/api-docs.md (относительный путь)
❌ Ошибка: /path/to/skill/references/api-docs.md (абсолютный путь)
❌ Ошибка: ../other-skill/references/api-docs.md (ссылка на другой навык)

Проблема 4: SKILL.md слишком длинный, превышен лимит токенов

Причина: SKILL.md превышает 5000 слов или содержит много подробной документации

Решение: Переместите подробное содержимое в каталог references/, ссылайтесь на него в SKILL.md

Итоги урока

Основные шаги создания пользовательских навыков:

Создание структуры каталогов: Минимальная структура (только SKILL.md) или полная структура (включая references/, scripts/, assets/)
Написание YAML frontmatter: Обязательные поля name (формат дефисов) и description (1-2 предложения)
Написание инструкций: Используйте форму imperative/infinitive, избегайте второго лица
Добавление ресурсов (необязательно): references/, scripts/, assets/
Проверка формата: Проверка с помощью openskills install ./my-skill
Синхронизация с AGENTS.md: Запустите openskills sync, чтобы ИИ-агент узнал
Проверка загрузки: Проверка с помощью openskills read my-skill

Предпросмотр следующего урока

В следующем уроке мы изучим Подробное описание структуры навыков.
Вы узнаете:
Полное описание полей SKILL.md
Лучшие практики для references/, scripts/, assets/
Как оптимизировать читаемость и удобство сопровождения навыков

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

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

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

Функция	Путь к файлу	Номер строки
Проверка YAML frontmatter	`src/utils/yaml.ts`	12-14
Извлечение полей YAML	`src/utils/yaml.ts`	4-7
Проверка формата при установке	`src/commands/install.ts`	242, 291, 340
Извлечение имени навыка	`src/commands/install.ts`	344-345

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

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

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

hasValidFrontmatter(content: string): boolean — Проверяет, начинается ли SKILL.md с ---
extractYamlField(content: string, field: string): string — Извлекает значение поля YAML (нежадное совпадение)

Создание пользовательских навыков ​

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

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

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

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

Основная идея ​

Что такое SKILL.md? ​

Минимальная vs полная структура ​

Пошаговое руководство ​

Шаг 1: Создание каталога навыка ​

Шаг 2: Написание основной структуры SKILL.md ​

Шаг 3: Написание инструкций ​

Шаг 4: Добавление упакованных ресурсов (необязательно) ​

4.1 Добавление references/ ​

4.2 Добавление scripts/ ​

Шаг 5: Проверка формата SKILL.md ​

Шаг 6: Синхронизация с AGENTS.md ​

Шаг 7: Проверка загрузки навыка ​

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

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

Проблема 1: При установке выводится "Invalid SKILL.md (missing YAML frontmatter)" ​

Проблема 2: ИИ-агент не распознаёт навык ​

Проблема 3: Ошибка разрешения пути к ресурсам ​

Проблема 4: SKILL.md слишком длинный, превышен лимит токенов ​

Итоги урока ​

Предпросмотр следующего урока ​

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

Создание пользовательских навыков

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

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

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

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

Основная идея

Что такое SKILL.md?

Минимальная vs полная структура

Пошаговое руководство

Шаг 1: Создание каталога навыка

Шаг 2: Написание основной структуры SKILL.md

Шаг 3: Написание инструкций

Шаг 4: Добавление упакованных ресурсов (необязательно)

4.1 Добавление references/

4.2 Добавление scripts/

Шаг 5: Проверка формата SKILL.md

Шаг 6: Синхронизация с AGENTS.md

Шаг 7: Проверка загрузки навыка

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

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

Проблема 1: При установке выводится "Invalid SKILL.md (missing YAML frontmatter)"

Проблема 2: ИИ-агент не распознаёт навык

Проблема 3: Ошибка разрешения пути к ресурсам

Проблема 4: SKILL.md слишком длинный, превышен лимит токенов

Итоги урока

Предпросмотр следующего урока

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