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

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

Точно понимать все требования к полям и спецификациям формата SKILL.md
Освоить принципы проектирования и сценарии использования references/, scripts/, assets/
Оптимизировать потребление токенов и производительность загрузки навыков
Избегать распространённых ошибок формата и проблем с разрешением путей
Использовать прогрессивную загрузку для повышения эффективности контекста AI

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

Вы уже научились создавать базовые навыки, но ещё не полностью владеете полной спецификацией SKILL.md. Ваш навык может столкнуться со следующими проблемами:

SKILL.md слишком длинный, что приводит к высокому потреблению токенов
Неопределённость в том, какой контент следует разместить в references/, а не в SKILL.md
AI-агент не может корректно загрузить ресурсы из scripts/ или assets/
Ошибки формата YAML frontmatter приводят к сбою установки

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

Проверка навыков: проверка соответствия существующих навыков спецификации Anthropic
Оптимизация производительности: решение проблем медленной загрузки навыков или превышения лимита токенов
Рефакторинг ресурсов: разбиение крупных навыков на SKILL.md + bundled resources
Разработка сложных навыков: написание полных навыков, включающих документацию API и исполняемые скрипты

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

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

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

✅ Прочитали раздел Создание пользовательских навыков
✅ Установили хотя бы один навык (понимание базового процесса)
✅ Знакомы с базовым синтаксисом YAML и Markdown

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

Философия проектирования SKILL.md

SKILL.md — это центр системы навыков Anthropic, использующая дизайн прогрессивной загрузки:

mermaid

graph LR
    A[Metadata<br/>name + description] -->|Всегда загружается| B[Context]
    B -->|AI определяет необходимость| C[SKILL.md<br/>Основные инструкции]
    C -->|Ссылки по запросу| D[Resources<br/>references/scripts/assets]

Преимущества трёхуровневой загрузки:

Уровень Metadata: name и description всех навыков всегда находятся в контексте, AI может быстро узнать о доступных навыках
Уровень SKILL.md: загружается только при необходимости, содержит основные инструкции (< 5000 слов)
Уровень Resources: подробная документация и исполняемые файлы загружаются по запросу, что позволяет избежать浪费 токенов

Классификация Bundled Resources

Каталог	Загружается в контекст	Сценарии использования	Примеры типов
`references/`	✅ По запросу	Подробная документация, спецификация API	Документация API, схема базы данных
`scripts/`	❌ Не загружается	Исполняемый код	Python/Bash скрипты
`assets/`	❌ Не загружается	Шаблоны, выходные файлы, изображения	JSON шаблоны, шаблонный код

Делайте вместе со мной

Шаг 1: Понимание полной спецификации YAML Frontmatter

Зачем: YAML frontmatter — это метаданные навыка, они должны соответствовать строгой спецификации

SKILL.md должен начинаться и заканчиваться ---:

yaml

---
name: my-skill
description: Use this skill when you need to demonstrate proper format.
---

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

Поле	Тип	Требования к формату	Пример
`name`	string	Формат с дефисами (kebab-case), без пробелов	`pdf-editor`, `api-client`
`description`	string	1-2 предложения, третье лицо	`Use this skill to edit PDF files`

Распространённые ошибки

Пример ошибки	Проблема	Способ исправления
`name: My Skill`	Содержит пробелы	Изменить на `name: my-skill`
`name: my_skill`	Формат с подчёркиваниями	Изменить на `name: my-skill`
`description: You should use this when...`	Второе лицо	Изменить на `description: Use this skill when...`
`description:` слишком длинный	Более 100 слов	Сократить до 1-2 предложений
Отсутствует закрывающий `---`	YAML не закрыт корректно	Добавить закрывающий разделитель

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

typescript

// src/utils/yaml.ts
export function hasValidFrontmatter(content: string): boolean {
  return content.trim().startsWith('---');
}

export function extractYamlField(content: string, field: string): string {
  const match = content.match(new RegExp(`^${field}:\\s*(.+?)$`, 'm'));
  return match ? match[1].trim() : '';
}

Шаг 2: Написание основного содержания SKILL.md (Imperative Form)

Зачем: AI-агенты ожидают командные инструкции, а не описательный диалог

Правильный подход:

markdown

## Instructions

To execute this task:

1. Read the input file
2. Process data using the algorithm
3. Generate output in specified format

Неправильный подход (избегайте):

markdown

## Instructions

You should execute this task by:

1. Reading the input file
2. Processing data using the algorithm
3. Generating output in specified format

Сравнительная таблица:

✅ Правильно (Imperative/Infinitive)	❌ Неправильно (Second Person)
"Load this skill when X"	"If you need Y"
"To accomplish Z, execute A"	"You should do Z"
"See references/guide.md"	"When you want to Z"

Мнемоника написания:

Начинайте с глагола: Create → Use → Return
Опустите "You": не пишите "You should"
Чёткие пути: при ссылках на ресурсы используйте префиксы references/, scripts/, assets/

Шаг 3: Использование references/ для управления подробной документацией

Зачем: поддерживать краткость SKILL.md, подробная документация загружается по запросу

Сценарии использования:

Документация API (описание endpoints более 500 слов)
Схема базы данных (структура таблиц, определение полей)
Подробные руководства (описание настроек, часто задаваемые вопросы)
Примеры кода (крупные фрагменты кода)

Структура каталога:

my-skill/
├── SKILL.md              (~2,000 слов, основные инструкции)
└── references/
    ├── api-docs.md       (подробная документация API)
    ├── database-schema.md (структура базы данных)
    └── troubleshooting.md (руководство по устранению неполадок)

Способ ссылок в SKILL.md:

markdown

## Instructions

To interact with the API:

1. Read the request parameters
2. Call the API endpoint
3. For detailed response format, see `references/api-docs.md`
4. Parse the response
5. Handle errors (see `references/troubleshooting.md`)

Пример references/api-docs.md:

markdown

# API Documentation

## Overview

This API provides endpoints for data processing.

## Endpoints

### POST /api/process

**Request:**
```json
{
  "input": "data to process",
  "options": {
    "format": "json"
  }
}

Response:

json

{
  "status": "success",
  "result": {
    "output": "processed data"
  }
}

Error Codes:

400: Invalid input format
500: Server error


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

**Рекомендации по размеру файлов в references/**:
- Один файл: рекомендуется < 10,000 слов
- Общий размер: рекомендуется < 50,000 слов (разбивка на несколько файлов)
- Именование: используйте формат с дефисами (`api-docs.md` вместо `API_Docs.md`)

:::

---

### Шаг 4: Использование scripts/ для выполнения детерминированных задач

**Зачем**: исполняемые скрипты не нужно загружать в контекст, подходят для повторяющихся задач

**Сценарии использования**:

- Преобразование данных (JSON → CSV, преобразование форматов)
- Обработка файлов (сжатие, распаковка, переименование)
- Генерация кода (генерация кода из шаблонов)
- Запуск тестов (модульные тесты, интеграционные тесты)

**Структура каталога**:

my-skill/ ├── SKILL.md └── scripts/ ├── process.py (скрипт Python) ├── transform.sh (скрипт Bash) └── validate.js (скрипт Node.js)


**Способ ссылок в SKILL.md**:

```markdown
## Instructions

To process the input data:

1. Validate the input file format
2. Execute the processing script:
   ```bash
   python scripts/process.py --input data.json --output result.json

Verify the output file
If validation fails, see scripts/validate.py for error messages


**Пример scripts/process.py**:

```python
#!/usr/bin/env python3
import json
import sys

def main():
    input_file = sys.argv[1]
    output_file = sys.argv[2]

    with open(input_file, 'r') as f:
        data = json.load(f)

    # Processing logic
    result = transform_data(data)

    with open(output_file, 'w') as f:
        json.dump(result, f, indent=2)

    print(f"✅ Processed {input_file} → {output_file}")

if __name__ == "__main__":
    main()

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

По сравнению с встроенным кодом в SKILL.md:

Характеристика	Встроенный код	scripts/
Потребление токенов	✅ Высокое	❌ Низкое
Повторное использование	❌ Плохое	✅ Хорошее
Тестируемость	❌ Сложно	✅ Легко
Ограничение сложности	❌ Ограничено токенами	✅ Без ограничений

Шаг 5: Использование assets/ для хранения шаблонов и выходных файлов

Зачем: шаблоны и выходные файлы не нужно загружать в контекст, экономит токены

Сценарии использования:

Шаблоны вывода (шаблоны JSON, XML, Markdown)
Шаблонный код (проектный шаблон, конфигурационные файлы)
Изображения и диаграммы (блок-схемы, архитектурные диаграммы)
Тестовые данные (примеры входных данных, ожидаемый вывод)

Структура каталога:

my-skill/
├── SKILL.md
└── assets/
    ├── template.json    (шаблон JSON)
    ├── boilerplate.js   (шаблонный код)
    └── diagram.png     (блок-схема)

Способ ссылок в SKILL.md:

markdown

## Instructions

To generate the output file:

1. Load the template: `assets/template.json`
2. Replace placeholders with actual data
3. Write to output file
4. For boilerplate code, see `assets/boilerplate.js`

Пример assets/template.json:

json

{
  "title": "{{ title }}",
  "description": "{{ description }}",
  "version": "{{ version }}",
  "author": "{{ author }}",
  "created_at": "{{ timestamp }}"
}

Использование шаблонов в скриптах:

python

import json
from string import Template

def generate_output(data, template_path):
    with open(template_path, 'r') as f:
        template_str = f.read()

    template = Template(template_str)
    output = template.safe_substitute(data)

    return output

Меры предосторожности для assets/

Не загружается в контекст: AI-агент не может напрямую читать содержимое, должен загружать через скрипты
Разрешение путей: используйте относительные пути, например assets/template.json
Размер файла: рекомендуется < 10MB на файл (избегать задержки передачи)

Шаг 6: Оптимизация размера файлов и производительности

Зачем: размер файлов напрямую влияет на потребление токенов контекста AI и скорость загрузки

Руководство по размеру файлов (официальные рекомендации):

Каталог	Ограничение размера	Поведение загрузки
SKILL.md	< 5,000 слов	Всегда загружается (при необходимости)
references/	Строгих ограничений нет	Загружается по запросу
scripts/	Не учитывается в токенах	Не загружается, только выполняется
assets/	Не загружается в контекст	Не загружается, только копируется

Советы по оптимизации производительности:

Разбивка references/:

bash

# ❌ Один большой файл (20,000 слов)
references/all-docs.md

# ✅ Разбивка на несколько небольших файлов (каждый < 5,000 слов)
references/
├── api-docs.md
├── database-schema.md
└── troubleshooting.md

Использование scripts/ для обработки данных:
markdown
```
# ❌ Встроение крупного блока кода в SKILL.md (потребляет токены)
## Instructions
Execute this code:
```python
# 500 строк кода...
```
✅ Ссылка на scripts/ (не потребляет токены)
Instructions
Execute: python scripts/processor.py
Упрощение SKILL.md:
- Сохраняйте только основные инструкции и шаги
- Переместите подробное описание в references/
- Используйте лаконичный командный язык

Проверка размера файлов:

bash

# Подсчёт слов в SKILL.md
wc -w my-skill/SKILL.md

# Подсчёт общего количества слов в references/
find my-skill/references -name "*.md" -exec wc -w {} + | tail -1

# Проверка размера файлов scripts/
du -sh my-skill/scripts/

Шаг 7: Понимание механизма разрешения ресурсов

Зачем: понимание правил разрешения путей помогает избежать ошибок ссылок

Концепция base directory:

Когда AI-агент загружает навык, openskills read выводит base directory:

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

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

Путь ссылки	Результат разрешения
`references/api.md`	`/base/directory/references/api.md`
`scripts/process.py`	`/base/directory/scripts/process.py`
`assets/template.json`	`/base/directory/assets/template.json`

Проверка в исходном коде:

typescript

// src/commands/read.ts
export function readSkill(skillNames: string[] | string): void {
  const skill = findSkill(name);
  const content = readFileSync(skill.path, 'utf-8');

  // Вывод base directory для AI для разрешения относительных путей
  console.log(`Base directory: ${skill.baseDir}`);
  console.log(content);
}

Примеры ошибок путей

❌ Неправильно	Проблема	✅ Правильно
`/absolute/path/to/api.md`	Использование абсолютного пути	`references/api.md`
`../other-skill/references/api.md`	Ссылка между навыками	`references/api.md`
`~/references/api.md`	Использование тильды	`references/api.md`

Шаг 8: Проверка формата навыка

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

Проверка с помощью openskills:

bash

npx openskills install ./my-skill

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

✔ Found skill: my-skill
  Description: Use this skill when you need to demonstrate proper format.
  Size: 2.1 KB

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

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

[ ] SKILL.md начинается с ---
[ ] Содержит поле name (формат с дефисами)
[ ] Содержит поле description (1-2 предложения)
[ ] YAML заканчивается ---
[ ] Основной текст использует форму imperative/infinitive
[ ] Все ссылки на references/, scripts/, assets/ используют относительные пути
[ ] Количество слов в SKILL.md < 5,000
[ ] Именование файлов в references/ использует формат с дефисами

Ручная проверка YAML frontmatter:

bash

# Проверка начинается ли с ---
head -1 my-skill/SKILL.md

# Проверка полей YAML (с помощью yq или других инструментов)
yq eval '.name' my-skill/SKILL.md

Шаг 9: Тестирование загрузки навыка

Зачем: убедиться, что навык корректно загружается в контекст AI

Тестирование с помощью openskills read:

bash

npx openskills read my-skill

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

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

---
name: my-skill
description: Use this skill when you need to demonstrate proper format.
---

# My Skill

## Instructions

To execute this task...

## Bundled Resources

For detailed information: see `references/skill-format.md`

Skill read: my-skill

Контрольные точки:

✅ Вывод содержит Base directory (используется для разрешения путей)
✅ Содержимое SKILL.md полное (включая YAML и основной текст)
✅ Нет ошибки "Invalid SKILL.md"
✅ Все пути ссылок отображаются корректно

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

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

✅ Понимать полную спецификацию полей SKILL.md
✅ Освоить сценарии использования references/, scripts/, assets/
✅ Уметь оптимизировать размер файлов и производительность загрузки навыков
✅ Знать, как проверить формат навыка и протестировать загрузку
✅ Понимать механизм разрешения ресурсов и base directory

Предупреждение о ловушках

Проблема 1: SKILL.md более 5000 слов приводит к превышению лимита токенов

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

Решение:

Переместите подробное содержание в каталог references/
В SKILL.md добавьте ссылку: See references/guide.md for details
Проверьте количество слов с помощью wc -w SKILL.md

Проблема 2: Скрипты в scripts/ не выполняются

Причина:

Скрипты缺少 права выполнения
Используется абсолютный путь вместо относительного

Решение:

bash

# Добавление прав выполнения
chmod +x my-skill/scripts/*.sh

# Использование относительного пути в SKILL.md
## Instructions
Execute: `python scripts/process.py`  # ✅ Правильно
Execute: `/path/to/my-skill/scripts/process.py`  # ❌ Неправильно

Проблема 3: Файлы в references/ загружаются по запросу, но AI не может прочитать

Причина: AI-агент неправильно разрешает путь references/

Решение:

Убедитесь, что openskills read выводит Base directory
При ссылке явно укажите: See references/api-docs.md in base directory
Избегайте использования абсолютных путей или ссылок между навыками

Проблема 4: Файлы в assets/ слишком большие, что вызывает задержку передачи

Причина: в assets/ хранятся крупные бинарные файлы (> 10MB)

Решение:

Сжатие изображений: используйте PNG вместо BMP, оптимизируйте качество JPEG
Разбивка данных: разбейте крупные наборы данных на несколько небольших файлов
Использование внешнего хранилища: для очень больших файлов предоставьте ссылку для скачивания вместо прямого включения

Проблема 5: Ошибка формата YAML frontmatter

Причина:

Отсутствует закрывающий ---
Значения полей содержат специальные символы (двоеточие, решётка) без кавычек

Решение:

yaml

# ❌ Неправильно: отсутствует закрывающий ---
---
name: my-skill
description: Use this skill: for testing
# Отсутствует ---

# ✅ Правильно: полное закрытие
---
name: my-skill
description: "Use this skill: for testing"
---

Проблема 6: Инструкции используют второе лицо (Second Person)

Причина: привычное использование "You should", "When you want"

Решение:

Используйте командный язык, начинающийся с глагола
Используйте "To do X, execute Y" вместо "You should do Y"
Используйте "Load this skill when Z" вместо "If you need Z"

Сравнительная таблица:

Второе лицо (❌ избегайте)	Командное (✅ рекомендуется)
"You should execute..."	"To execute X, run..."
"When you want to..."	"Load this skill when..."
"If you need..."	"Use X to accomplish Y"

Итог урока

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

YAML frontmatter: обязательные поля name (формат с дефисами) и description (1-2 предложения)
Формат основного текста: используйте форму imperative/infinitive, избегайте второго лица
references/: храните подробную документацию, загружайте в контекст по запросу (< 10,000 слов/файл)
scripts/: храните исполняемые скрипты, не загружайте в контекст, подходят для детерминированных задач
assets/: храните шаблоны и выходные файлы, не загружайте в контекст
Размер файлов: SKILL.md < 5,000 слов, references/ можно разбить, scripts/ без ограничений
Разрешение путей: используйте относительные пути (references/, scripts/, assets/), разрешение на основе base directory
Методы проверки: используйте openskills install для проверки формата, openskills read для тестирования загрузки

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

В следующем уроке мы изучим CI/CD интеграцию.
Вы научитесь:
Использовать флаг -y/--yes в среде CI/CD
Автоматизировать установку и синхронизацию навыков
Интегрировать OpenSkills в GitHub Actions, GitLab CI

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

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

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

Функция	Путь к файлу	Строка
Проверка YAML frontmatter	`src/utils/yaml.ts`	12-14
Извлечение полей YAML	`src/utils/yaml.ts`	4-7
Команда чтения навыка	`src/commands/read.ts`	1-49
Вывод base directory	`src/commands/read.ts`	42
Проверка формата при установке	`src/commands/install.ts`	242, 291, 340

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

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 (нежадное совпадение)
readSkill(skillNames: string[] | string): void - чтение навыка в стандартный вывод (для использования AI)

Подробное описание структуры навыков ​

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

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

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

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

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

Философия проектирования SKILL.md ​

Классификация Bundled Resources ​

Делайте вместе со мной ​

Шаг 1: Понимание полной спецификации YAML Frontmatter ​

Шаг 2: Написание основного содержания SKILL.md (Imperative Form) ​

Шаг 3: Использование references/ для управления подробной документацией ​

Шаг 5: Использование assets/ для хранения шаблонов и выходных файлов ​

Шаг 6: Оптимизация размера файлов и производительности ​

✅ Ссылка на scripts/ (не потребляет токены) ​

Instructions ​

Шаг 7: Понимание механизма разрешения ресурсов ​

Шаг 8: Проверка формата навыка ​

Шаг 9: Тестирование загрузки навыка ​

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

Предупреждение о ловушках ​

Проблема 1: SKILL.md более 5000 слов приводит к превышению лимита токенов ​

Проблема 2: Скрипты в scripts/ не выполняются ​

Проблема 3: Файлы в references/ загружаются по запросу, но AI не может прочитать ​

Проблема 4: Файлы в assets/ слишком большие, что вызывает задержку передачи ​

Проблема 5: Ошибка формата YAML frontmatter ​

Проблема 6: Инструкции используют второе лицо (Second Person) ​

Итог урока ​

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

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

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

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

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

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

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

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

Философия проектирования SKILL.md

Классификация Bundled Resources

Делайте вместе со мной

Шаг 1: Понимание полной спецификации YAML Frontmatter

Шаг 2: Написание основного содержания SKILL.md (Imperative Form)

Шаг 3: Использование references/ для управления подробной документацией

Шаг 5: Использование assets/ для хранения шаблонов и выходных файлов

Шаг 6: Оптимизация размера файлов и производительности

✅ Ссылка на scripts/ (не потребляет токены)

Instructions

Шаг 7: Понимание механизма разрешения ресурсов

Шаг 8: Проверка формата навыка

Шаг 9: Тестирование загрузки навыка

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

Предупреждение о ловушках

Проблема 1: SKILL.md более 5000 слов приводит к превышению лимита токенов

Проблема 2: Скрипты в scripts/ не выполняются

Проблема 3: Файлы в references/ загружаются по запросу, но AI не может прочитать

Проблема 4: Файлы в assets/ слишком большие, что вызывает задержку передачи

Проблема 5: Ошибка формата YAML frontmatter

Проблема 6: Инструкции используют второе лицо (Second Person)

Итог урока

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

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