Навыки (Skills)

Навыки — это переиспользуемые пакеты инструкций, загружаемые по необходимости (модель Agent Skills от Anthropic). Каждый навык — это директория с файлом SKILL.md: YAML-фронтматтер плюс тело в markdown. SGR Agent Core автоматически регистрирует name + description навыка в системном промпте, чтобы агент мог вызвать навык самостоятельно, а также показывает навыки как команды через ACP, CLI и HTTP-сервер.

Как выглядит навык

skills/
  citation-style/
    SKILL.md
  concise-answer/
    SKILL.md

SKILL.md:

---
name: citation-style
description: Formats research citations in a consistent numbered style. Use when writing reports that reference web sources.
---

# Citation style

1. Number every source in order: [1], [2], ...
2. Collect all sources under a `## Sources` heading.

Фронтматтер

поле	обязательное	примечания
`name`	да	≤ 64 символов; строчные буквы, цифры, дефисы; без `anthropic`/`claude`
`description`	да	непустое, ≤ 1024 символов; от третьего лица, что и когда
`license`	нет	SPDX-идентификатор или текст
`allowed-tools`	нет	рекомендательный список инструментов навыка
`metadata`	нет	произвольный словарь (версия, автор, ...)
`disable-model-invocation`	нет	`true` скрывает навык из каталога модели (только команда пользователя)
`user-invocable`	нет	`false` скрывает навык из меню команд (только для модели)

Если name не указан, берётся имя директории.

Прогрессивное раскрытие

Уровень 1 — метаданные: name + description всегда попадают в системный промпт (компактный блок каталога), чтобы модель знала о существовании навыка.
Уровень 2 — тело: тело SKILL.md загружается только при вызове навыка (инструмент use_skill возвращает его в диалог).
Уровень 3 — ресурсы: вложенные файлы читаются только при необходимости.

Включение навыков

Навыки работают из коробки: по умолчанию агент сканирует

./.agent/skills (проектные, относительно текущего каталога, CWD)
~/.agent/skills (личные)

Если этих папок нет или они пусты — ничего не ломается, агент работает без навыков. Чтобы настроить, добавьте блок skills в агента (или глобально, на верхнем уровне) в config.yaml:

agents:
  sgr_agent:
    base_class: SGRToolCallingAgent
    tools:
      - reasoningtool
    skills:
      enabled: true            # по умолчанию true; false — отключить навыки
      paths:                   # переопределяет корни по умолчанию (относительно CWD)
        - ./my-skills
      include: null            # необязательный список активируемых имён
      exclude: null            # необязательный список запрещённых имён

skills.paths, если задан, заменяет корни по умолчанию. Последующие корни переопределяют предыдущие по имени. Бюджет описания на запись в промпте — глобальная настройка execution.max_skill_desc_chars (по умолчанию 500).

Когда доступен хотя бы один навык, в набор инструментов агента автоматически добавляется инструмент use_skill.

Вызов навыка

Навык вызывается двумя способами:

Самостоятельно (решает модель). В системный промпт добавляется блок AVAILABLE_SKILLS со списком навыков, доступных модели, и указанием вызвать use_skill, когда задача подходит под навык. Вызов use_skill <name> возвращает тело навыка в диалог (уровень 2 progressive disclosure).
Явно (ссылается пользователь). Если в сообщении пользователя упомянут навык по имени со слешем — /citation-style — тело этого навыка добавляется в промт. Это работает во всех режимах (ACP, CLI и OpenAI-совместимый сервер), потому что ссылка разворачивается централизованно в AgentFactory.create. Ссылка может быть где угодно в сообщении (используй /concise-answer); слеши внутри URL/путей игнорируются.

Навыки как команды (обнаружение)

ACP (sgracp): навыки, доступные пользователю, объявляются клиенту как available_commands — они попадают в меню слэш-команд клиента.
CLI: sgrsh --list-skills -c config.yaml печатает доступные навыки.
HTTP-сервер: GET /v1/skills (опционально ?model=<agent>) перечисляет навыки по агентам.

Безопасность и доверие

Навыки — это доверенный контент, наравне с config.yaml и кодом пользовательских инструментов: тело навыка дословно попадает в контекст модели при вызове. Корни по умолчанию ./.agent/skills и ~/.agent/skills сканируются автоматически, поэтому открытие репозитория с директорией .agent/skills/ загрузит инструкции его авторов. Запускайте навыки только из доверенных источников и проверяйте сторонние SKILL.md перед использованием. Загрузчик ограничивает SKILL.md размером 1 МиБ и пропускает нечитаемые файлы.

Советы по написанию

Пишите description от третьего лица; указывайте что делает и когда применять — именно по этому модель выбирает навык.
Держите SKILL.md компактным (до ~500 строк); длинный материал выносите в отдельные файлы.
Используйте имена-герундии или существительные (processing-pdfs, citation-style); избегайте расплывчатых helper или utils.