# `:skills` — парсер SKILL.md (KMP, JVM-only)

## Что это

Парсер и runtime для навыков агента в формате [opencode Skills](https://docs.opencode.dev):

- **SKILL.md / \*.yaml** с YAML-frontmatter (`name`, `description`,
  `allowed-tools`, etc.) и markdown-телом.
- Реестр `SkillCatalog`, лоадер `SkillLoader` (поиск по
  `~/.agentik/skills/`).
- `Skill` имеет стабильный id, описание, может требовать определённые
  tools (`allowed-tools: [run_command, write_file]`) — это контролируется
  на уровне вызова.
- Загруженные скиллы аггрегируются в system-prompt через
  `Skill.toSystemPromptSection()` или подгружаются по требованию через
  tool `read_skill`.

Решает задачу: агенту нужно объяснить "что я умею" на разных языках
(нативный skill-вызов vs. описание), нужно уметь включать/выключать
навыки по требованию, и нужно хранить текстовые навыки прямо в
git-репозитории (а не в БД).

## Где используется

- `:standalone` подгружает все SKILL.md из `~/.agentik/skills/`
  и инструментового скилл-майнера (skill-mining: создание новых
  SKILL.md по LLM-рефлексии).
- Активно юзается для: `code-review`, `arch-summary`, `telegram-reply`,
  любых "habits" агента.

## Как подключить

```kotlin
kotlin {
    sourceSets.commonMain.dependencies {
        api("pw.binom.agentik:skills:0.1.0")
    }
}
```

## Версии

`gradle/libs.versions.toml` → `[versions] agentik-skills`.

## Пример SKILL.md

```markdown
---
name: code-review
description: Review uncommitted diff and produce line-anchored comments.
allowed-tools: [run_command, read_file]
---

You are a strict reviewer. For every change in the diff, output:
- File: <path>
- Severity: <nit|warning|blocker>
- Comment: <one sentence>

Only mention issues that are objectively wrong. Do not refactor.
```

## Тесты

```
./gradlew :skills:jvmTest
```

Покрывают: парсинг yaml-frontmatter, обработку отсутствующих полей,
unicode-имена, дубликаты id, очень большое тело.

## Чего здесь НЕТ

- Никакого HTTP / tool-вызова. Парсер и реестр — не более.
- Никакой БД. SKILL.md живут в файлах под управлением пользователя.

## Текущий статус

Используется продакшеном. Парсер простой и предсказуемый; расширять
формат frontmatter можно без поломок (новые поля игнорируются).