Настройка скиллов

Приоритет CLI (рекомендуется): используйте команды craft-agent skill ... вместо прямого редактирования файлов SKILL.md.

• craft-agent skill --help
• Канонический справочник команд: craft-cli.md

Что такое скиллы?

Скиллы — это специализированные инструкции, которые расширяют возможности Claude для конкретных задач. Они используют тот же формат SKILL.md, что и Claude Code SDK, поэтому скиллы полностью совместимы между системами.

Ключевые моменты:

• Скиллы вызываются через slash-команды (например, /commit, /review-pr)
• Скиллы могут автоматически запускаться по шаблонам файлов (globs)
• Скиллы могут заранее разрешать определённые инструменты для выполнения без запроса
• Формат SKILL.md идентичен тому, что Claude Code использует внутренне

Тот же формат, что и Claude Code SDK

AIKraft Agents использует идентичный формат SKILL.md, как и Claude Code SDK. Это означает:

1. Совместимость формата: любой скилл, написанный для Claude Code, работает в AIKraft Agents
2. Те же поля frontmatter: name, description, globs, alwaysAllow, requiredSources
3. Та же структура содержимого: Markdown-тело с инструкциями для Claude

Что добавляет AIKraft Agents:

• Визуальные иконки: отображение пользовательских иконок в UI для каждого скилла
• Организация по workspace: скиллы ограничены workspace
• Управление через UI: просмотр, редактирование и валидация скиллов через интерфейс

Приоритет скиллов

Когда скилл вызывается (например, /commit):

1. Сначала проверяется скилл workspace — если существует ~/.craft-agent/workspaces/{id}/skills/commit/SKILL.md, используется он
2. Скилл SDK как запасной вариант — если скилл workspace отсутствует, используется встроенный скилл SDK

Это позволяет:

• Переопределять скиллы SDK — создайте скилл workspace с тем же slug, чтобы заменить встроенное поведение
• Расширять скиллы SDK — ссылайтесь на поведение SDK в собственном скилле и добавляйте инструкции, специфичные для workspace
• Создавать новые скиллы — добавляйте полностью новые скиллы, которых нет в SDK

Хранение скиллов

Скиллы хранятся как папки:

~/.craft-agent/workspaces/{workspaceId}/skills/{slug}/
├── SKILL.md          # Обязательно: определение скилла (тот же формат, что и Claude Code SDK)
├── icon.svg          # Рекомендуется: иконка скилла для отображения в UI
├── icon.png          # Альтернатива: иконка PNG
└── (other files)     # Необязательно: дополнительные ресурсы

Формат SKILL.md

Формат идентичен скиллам Claude Code SDK:

---
name: "Skill Display Name"
description: "Brief description shown in skill list"
globs: ["*.ts", "*.tsx"]     # Необязательно: шаблоны файлов, которые активируют скилл
alwaysAllow: ["Bash"]        # Необязательно: инструменты, которые всегда разрешены
requiredSources:             # Необязательно: источники, которые автоматически включаются при вызове
  - linear
---

# Skill Instructions

Your skill content goes here. This is injected into Claude's context
when the skill is active.

## Guidelines

- Specific instructions for Claude
- Best practices to follow
- Things to avoid

## Examples

Show Claude how to perform the task correctly.

Поля метаданных

name (обязательно)

Отображаемое имя скилла. Показывается в UI и списке скиллов.

description (обязательно)

Краткое описание (1–2 предложения), объясняющее, что делает скилл.

globs (необязательно)

Массив glob-шаблонов. Когда выполняется работа с файлом, соответствующим этим шаблонам, скилл может быть автоматически предложен или активирован.

globs:
  - "*.test.ts"           # Тестовые файлы
  - "*.spec.tsx"          # Тестовые файлы React
  - "**/__tests__/**"     # Тестовые каталоги

alwaysAllow (необязательно)

Массив имён инструментов, которые автоматически разрешаются, когда этот скилл активен. Полезно для скиллов, которым нужны определённые инструменты без запроса.

alwaysAllow:
  - "Bash"                # Разрешить команды bash
  - "Write"               # Разрешить запись файлов

requiredSources (необязательно)

Массив slug источников, которые автоматически включаются при вызове этого скилла. Когда пользователь упоминает скилл, перечисленные источники включаются для сессии до запуска агента — поэтому инструменты из этих источников доступны с первого хода.

Источники должны существовать в workspace и быть аутентифицированы. Неаутентифицированные или отсутствующие источники молча пропускаются (существующий механизм авто-включения runtime обрабатывает их как запасной вариант).

requiredSources:
  - linear               # Автоматически включить источник Linear
  - github               # Автоматически включить источник GitHub

Создание скилла

1. Создайте папку скилла

mkdir -p ~/.craft-agent/workspaces/{ws}/skills/my-skill

2. Напишите SKILL.md

---
name: "Code Review"
description: "Review code changes for quality, security, and best practices"
globs: ["*.ts", "*.tsx", "*.js", "*.jsx"]
---

# Code Review Skill

When reviewing code, focus on:

## Quality Checks
- Consistent code style
- Clear naming conventions
- Appropriate abstractions

## Security Checks
- Input validation
- Authentication/authorization
- Sensitive data handling

## Best Practices
- Error handling
- Performance considerations
- Test coverage

3. Добавьте иконку (ВАЖНО)

У каждого скилла должна быть визуально релевантная иконка. Это помогает пользователям быстро находить скиллы в UI.

Требования к иконке:

• Имя файла: должно быть icon.svg, icon.png, icon.jpg или icon.jpeg
• Формат: предпочтителен SVG (масштабируется, чёткий в любом размере)
• Размер: для PNG/JPG используйте минимум 64x64 пикселя

Как получить иконку:

1. Ищите в онлайн-библиотеках иконок:
   • Heroicons — лицензия MIT
   • Feather Icons — лицензия MIT
   • Simple Icons — иконки брендов (git, npm и т. д.)
2. Используйте WebFetch для загрузки:
   terminalbash

   # Найдите подходящий URL иконки и загрузите её
   WebFetch to get SVG content, then save to icon.svg

3. Соответствие назначению скилла:
   • Скилл Git/commit → иконка git или commit
   • Скилл тестов → иконка галочки или пробирки
   • Скилл деплоя → иконка ракеты или облака
   • Скилл ревью → иконка лупы или глаза

4. Провалидируйте скилл

ВАЖНО: всегда выполняйте валидацию после создания или редактирования скилла:

skill_validate({ skillSlug: "my-skill" })

Это проверяет:

• формат slug (только строчные буквы, цифры и дефисы)
• наличие и читаемость SKILL.md
• валидность YAML frontmatter
• наличие обязательных полей (name, description)
• содержимое не пустое
• формат иконки (если она есть)

Примеры скиллов

Скилл Commit Message

---
name: "Commit"
description: "Create well-formatted git commit messages"
alwaysAllow: ["Bash"]
---

# Commit Message Guidelines

When creating commits:

1. **Format**: Use conventional commits
   - `feat:` New feature
   - `fix:` Bug fix
   - `docs:` Documentation
   - `refactor:` Code refactoring
   - `test:` Adding tests

2. **Style**:
   - Keep subject line under 72 characters
   - Use imperative mood ("Add feature" not "Added feature")
   - Explain why, not what (the diff shows what)

3. **Co-authorship**:
   Always include: `Co-Authored-By: Claude <noreply@anthropic.com>`

Рекомендуемая иконка: иконка Git commit из Heroicons или Simple Icons

Скилл Team Standards

---
name: "Team Standards"
description: "Enforce team coding conventions and patterns"
globs: ["src/**/*.ts", "src/**/*.tsx"]
---

# Team Coding Standards

## File Organization
- One component per file
- Co-locate tests with source files
- Use barrel exports (index.ts)

## Naming Conventions
- Components: PascalCase
- Hooks: camelCase with `use` prefix
- Constants: SCREAMING_SNAKE_CASE

## Import Order
1. External packages
2. Internal packages (@company/*)
3. Relative imports

Рекомендуемая иконка: иконка списка на доске или чек-листа

Скилл с обязательными источниками

---
name: "Linear Triage"
description: "Triage and prioritize Linear issues"
requiredSources:
  - linear
---

# Linear Triage

When triaging issues:
1. List unassigned issues from the current sprint
2. Categorize by severity
3. Suggest assignees based on expertise

Рекомендуемая иконка: иконка канбан-доски или списка

Когда этот скилл вызывается, источник linear автоматически включается для сессии — не нужно переключать его вручную.

Переопределение скиллов SDK

Чтобы настроить встроенный скилл SDK, например /commit:

1. Создайте ~/.craft-agent/workspaces/{ws}/skills/commit/SKILL.md
2. Напишите собственные инструкции
3. Добавьте иконку
4. Выполните skill_validate({ skillSlug: "commit" })

Ваш скилл будет использоваться вместо встроенной версии SDK.

Это полезно для:

• добавления формата commit-сообщений, специфичного для команды
• принудительного соблюдения стандартов кодирования, специфичных для проекта
• настройки критериев ревью под ваш кодовый базис

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

1. Будьте конкретны: давайте Claude чёткие и выполнимые инструкции
2. Добавляйте примеры: показывайте ожидаемый формат вывода
3. Устанавливайте границы: объясняйте, чего НЕ делать
4. Оставайтесь сфокусированными: один скилл = одна конкретная задача или область
5. Добавляйте релевантную иконку: это делает скиллы легко узнаваемыми в UI
6. Всегда валидируйте: выполняйте skill_validate после создания или редактирования

Устранение неполадок

Скилл не загружается:

• Проверьте формат slug (только строчные буквы, цифры и дефисы)
• Убедитесь, что SKILL.md существует и доступен для чтения
• Выполните skill_validate для подробных ошибок

Скилл не срабатывает:

• Проверьте, что glob-шаблоны соответствуют вашим файлам
• Убедитесь, что скилл находится в правильном workspace

Иконка не отображается:

• Используйте поддерживаемые форматы: svg, png, jpg, jpeg
• Файл должен называться icon.{ext} (а не my-icon.svg)
• Проверьте, что файл иконки не повреждён
• Для SVG убедитесь, что структура XML валидна