---
name: koda-skill-maker
description: "Мета-навык создания новых навыков для агентов по запросу пользователя"
license: MIT
metadata:
  author: koda
  version: "1.0.0"
---

# Создание агентского навыка

Мета-навык для создания новых навыков агентов, соответствующих открытому стандарту [agentskills.io](https://agentskills.io/specification).

## Создание навыка

На высоком уровне процесс выглядит так:

1. Определить, что должен делать навык и примерно как он должен это делать.
2. Написать черновик навыка.
3. Создать несколько тестовых промптов и опровобовать их с использованием навыка.
4. Помочь пользователю оценить результаты как качественно, так и количественно.
5. Переписать навык на основе отзывов пользователя (а также при обнаружении явных недостатков в количественных тестах).
6. Повторять до достижения удовлетворенности.
7. Расширить набор тестов и попробовать снова на большем масштабе.

## Применение навыка

Твоя задача при использовании этого навыка - понять, на каком этапе находится пользователь, и помочь ему продвинуться дальше.
Например, если пользователь говорит: «Я хочу сделать навык для X», вы помогаете уточнить детали, пишете черновик, создаете тесты, определяете критерии оценки и запускаете цикл.

Если у пользователя уже есть черновик, можно сразу переходить к этапу оценки и итераций.

Будьте гибкими: если пользователь скажет «Мне не нужны сложные оценки, просто посмотри на глаз», следуйте его пожеланию.

После завершения работы над навыком можно запустить оптимизатор описания (отдельный скрипт) для улучшения точности срабатывания навыка.

## Общение с пользователем

Этим инструментом могут пользоваться люди с разным уровнем технической подготовки.

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

* Термины «оценка» (evaluation) и «бенчмарк» допустимы, но на грани.
* Для «JSON» и «ассершн» (assertion) убедись, что пользователь понимает их значение, прежде чем использовать без объяснений.

Кратко поясняй термины, если сомневаешься.

## Создание навыка

### Определение намерений

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

1. Что этот навык должен позволить делать Koda?
2. Когда навык должен срабатывать? (фразы пользователя, контекст).
3. Какой ожидаемый формат вывода?
4. Нужно ли настраивать тест-кейсы?
  Навыки с объективно проверяемым результатом (преобразование файлов, извлечение данных, генерация кода) выигрывают от тестов.
  Для субъективных навыков (стиль письма, искусство) тесты часто не нужны.

### Интервью и исследование

Проактивно спрашивай о пограничных случаях, форматах, примерах файлов и критериях успеха.
Не пиши тесты, пока не прояснишь эти детали.

Проверьте доступные MCP и инструменты - используйте их для поиска документации или лучших практик.

### Написание SKILL.md

Документ должен быть на русском языке.

Заполни frontmatter:

- **`name`**: Идентификатор навыка.
  Требования: латиница в нижнем kebab-case, 1-64 символов, должно совпадать с именем директории
- **`description`**: Когда срабатывает и что делает.
  Требования: 1-1024 символов, краткое описание навыка на русском языке.
  Это основной механизм активации.
  Пиши описание немного «настойчивым», чтобы Koda не игнорировал навык там, где он полезен.

#### Проверка имени

```
✅ Валидно: code-review, sprint-planner, github-flow
❌ Невалидно: Code-Review (верхний регистр), -my-skill (дефис в начале), my--skill (двойной дефис)
```

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

#### Анатомия навыка

```
.agents/skills/<skill-name>/
    └── SKILL.md
        ├── YAML frontmatter (name, description)
        └── Markdown-инструкции
```

#### Паттерны написания

- **Метаданные** (имя + описание) - всегда в контексте (~100 слов).
- **Тело SKILL.md** - в контексте при срабатывании (<500 строк).

Используй повелительное наклонение.
Объясняй «почему» нужно делать именно так - современные LLM лучше работают, когда понимают логику ограничений.

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