Agent Skills

Agent Skills — открытый стандарт процедурных знаний для AI-агентов. Навык — это папка с файлом SKILL.md (метаданные + инструкции), опционально сопровождаемая скриптами и ресурсами. Навыки загружаются по принципу progressive disclosure: агент видит только имя и описание каждого навыка в системном промпте и активирует полные инструкции лишь при релевантной задаче.

Архитектура

graph TB
    subgraph "Discovery"
        Embedded["Встроенные<br/>skills.FS (embed)"]
        Global["Глобальные<br/>~/.config/creo/skills/"]
        Project["Проектные<br/>.creo/skills/"]
        Auto["Автоскиллы<br/>.creo/autoskills/"]
        Claude[".claude/skills/"]
        Opencode[".opencode/skills/"]
    end

    subgraph "Parsing"
        FM["YAML frontmatter<br/>name, description"]
        H1["H1 fallback<br/># Name"]
        Meta["_meta.json<br/>slug"]
        Card["skill-card.md<br/>## Description"]
        Dir["Имя директории"]
    end

    subgraph "Output"
        Skills["[]Skill<br/>dedup по name"]
        Catalog["Catalog<br/>[]Summary для system prompt"]
        SlashCat["SlashCatalog<br/>autocomplete"]
    end

    Embedded --> Skills
    Global --> Skills
    Project --> Skills
    Auto --> Skills
    Claude --> Skills
    Opencode --> Skills

    FM --> Skills
    H1 --> Skills
    Meta --> Skills
    Card --> Skills
    Dir --> Skills

    Skills --> Catalog
    Skills --> SlashCat

Структура SKILL.md

Файл SKILL.md — обязательный файл в каждой директории навыка. Содержит YAML frontmatter с метаданными и Markdown-тело с инструкциями.

1---
2name: my-skill
3description: Краткое описание навыка для системного промпта.
4---
5
6# My Skill
7
8Подробные инструкции для агента. Загружаются в контекст только при активации навыка.

Поля frontmatter

* Если frontmatter отсутствует или поля пустые, срабатывает fallback chain (см. ниже).

Fallback chain парсинга

При отсутствии name или description в frontmatter, парсер parseRawSkill использует последовательность fallback'ов:

frontmatter.name → H1 в body → _meta.json:slug → имя директории
frontmatter.description → первая строка после H1 → skill-card.md:## Description → "Skill: <dir>"

1. YAML frontmatter

1---
2name: my-skill
3description: Does something useful.
4---

Парсится через splitFrontmatter → yaml.Unmarshal. Если YAML невалидный — попытка lenientWrap (квотирование значений с двоеточиями для cross-client compat).

2. H1 fallback

Если frontmatter пустой, первый заголовок # Name становится именем, а первая non-empty non-heading строка после него — описанием:

1# My Skill
2
3This is the description line.

3. Sidecar файлы

Если name или description всё ещё пустые после frontmatter и H1, EnrichFromSidecars читает:

• _meta.json → {"slug": "skill-name"} — slug становится именем
• skill-card.md → секция ## Description, первая non-empty строка — описание

4. Имя директории

Последний fallback: имя директории навыка становится именем, а описание — "Skill: <dirname>".

Discovery — обнаружение навыков

Discover(globalDir, projectDir) сканирует директории в строго заданном порядке приоритета.

Директории и приоритеты

Дедупликация

dedupSkills оставляет первое появление навыка по имени — seen[name] = true. Поскольку директории сканируются в порядке приоритета, project перебивает global, native перебивает external, autoskill перебивает regular.

 1func dedupSkills(ordered []Skill) []Skill {
 2    seen := map[string]bool{}
 3    var out []Skill
 4    for _, s := range ordered {
 5        if seen[s.Name] { continue }
 6        seen[s.Name] = true
 7        out = append(out, s)
 8    }
 9    return out
10}

Кросс-экосистемная совместимость

Creo автоматически обнаруживает навыки из .claude/skills/ и .opencode/skills/ — как проектные, так и глобальные. Они появляются в autocomplete и /skills наравне с нативными. Не нужно ничего копировать или конвертировать.

Структура директории навыка

my-skill/
├── SKILL.md          # обязательный — frontmatter + инструкции
├── _meta.json        # опционально — slug для fallback
├── skill-card.md     # опционально — описание для fallback
├── references/       # опционально — файлы ресурсов
├── templates/        # опционально — шаблоны
└── scripts/          # опционально — скрипты

Каталог (Catalog)

Catalog(skills) строит tier-1 summary list для системного промпта — агент видит только имена и краткие описания.

1type Summary struct {
2    Name        string
3    Description string  // обрезано до 200 символов
4}

FormatCatalog рендерит список в Markdown для system prompt:

1- **code-review**: Conducts multi-axis code review...
2- **test-driven-development**: Drives development with tests...

SlashCatalog и autocomplete

Навыки интегрированы в SlashCatalog (internal/command/catalog.go) — единый каталог для autocomplete при вводе /. Навыки появляются наравне со встроенными и пользовательскими командами. Недавно использованные команды наверху.

Активация навыка

Два способа активации:

1. Через tool skill

Агент вызывает инструмент skill с именем навыка. Полные инструкции загружаются в контекст как сообщение:

1skill(name: "code-review-skill")

2. Через slash-команду

Пользователь вводит /<skill-name> — навык активируется как сообщение. Автокомплит показывает все доступные навыки.

Структура Skill

1type Skill struct {
2    Name        string  // имя навыка
3    Description string  // краткое описание
4    Location    string  // путь к SKILL.md
5    BaseDir     string  // директория навыка (для sidecar файлов)
6    Body        string  // полный текст инструкций (после frontmatter)
7    Scope       string  // "builtin", "global", "project", "project-autoskill", ...
8}

IsAutoskill() — true если scope заканчивается на "autoskill".

Skillcreator — метаданные автоскиллов

internal/skillcreator — meta tracking для навыков, созданных агентом (автоскиллов).

.meta.json

Рядом с SKILL.md хранится .meta.json с метаданными использования:

1{
2    "use_count": 3,
3    "last_used": "2026-01-15T10:30:00Z",
4    "created_by": "agent",
5    "created_at": "2026-01-10T14:00:00Z"
6}

API

Skillhub — реестры навыков

internal/skillhub — клиент для публичных реестров навыков. Поиск, просмотр и установка навыков прямо в чате через инструмент skillhub.

Реестры

Интерфейс Registry

1type Registry interface {
2    Name() string
3    Search(ctx context.Context, query string, limit int) ([]SearchHit, error)
4    Browse(ctx context.Context, sort string, limit int) ([]SearchHit, error)
5    Detail(ctx context.Context, slug string) (*SkillInfo, error)
6    Install(ctx context.Context, slug string) (*InstallResult, error)
7}

Типы данных

Поиск идёт по всем реестрам одновременно. Результаты префиксируются именем реестра: clawhub/my-skill, skillsdb/another-skill.

Файлы