AI Knowledge Base

Архитектура Навыка

Архитектура навыка

Abstract

Минимальный файловый skill — директория с SKILL.md. Дополнительные references, scripts и assets нужны только тогда, когда улучшают выполнение или экономят контекст.

Типичная структура

my-skill/
├── SKILL.md              # метаданные, триггеры и основной маршрут
├── references/           # справочники и подробные инструкции
├── scripts/              # повторяемые проверки и преобразования
└── assets/               # шаблоны и материалы для результата

Названия дополнительных каталогов зависят от среды. Важнее, чтобы SKILL.md явно говорил, какой файл читать или запускать и в какой ситуации.

Frontmatter

Для Codex-подобного файлового формата базовое описание выглядит так:

---
name: knowledge-base-editor
description: Проверяет и обновляет Markdown-базу знаний; используй для редакторского аудита, терминологии, frontmatter и внутренних ссылок.
---
  • name должно быть коротким, устойчивым и различимым.
  • description отвечает сразу на два вопроса: что делает навык и когда его применять.
  • Дополнительные поля считай платформенными: проверяй их поддержку в своём клиенте.

Слишком общее описание вызывает ложные срабатывания. Описание без триггеров делает хороший навык почти невидимым.

Основная инструкция

Практичная последовательность разделов:

  1. Назначение — наблюдаемый результат.
  2. Когда использовать — запросы и условия запуска.
  3. Когда не использовать — соседние задачи и границы.
  4. Входы — обязательные файлы, данные и решения пользователя.
  5. Процедура — действия в правильном порядке.
  6. Инструменты — разрешённые tools и предпочтительный способ применения.
  7. Безопасность — ограничения, секреты и подтверждения.
  8. Проверка — команды, инварианты и Definition of Done.
  9. Fallback — что делать без сети, зависимости или доступа.

Что выносить из SKILL.md

МатериалКудаЗачем
Большой справочникreferences/не засорять контекст каждого запуска
Детерминированная проверкаscripts/получать воспроизводимый результат
Шаблон документаassets/не генерировать структуру заново
Секретsecret store / envне хранить ключи внутри skill
Постоянное правило проектаproject instructionsприменять независимо от выбранного skill

Правила для scripts

  • предпочитай маленькие scripts с одной ответственностью;
  • опиши вход, выход и код возврата;
  • используй dry-run для изменяющих операций;
  • не скрывай сетевые запросы или удаление файлов;
  • фиксируй зависимости и минимальные версии;
  • не печатай secrets в stdout и логи.

Definition of Done

Критерии описывают состояние результата:

  • обязательные поля присутствуют;
  • изменены только файлы в области задачи;
  • ссылки разрешаются;
  • тесты и форматтер проходят;
  • внешние утверждения имеют источники;
  • значимые side effects подтверждены;
  • пользователь получил путь к артефакту или краткий отчёт.

«Выглядит правильно» и «агент закончил работу» не являются проверками.

Минимальный шаблон

---
name: example-skill
description: Что делает навык и когда его использовать.
---
 
# Example skill
 
## Когда использовать
 
## Когда не использовать
 
## Входы и зависимости
 
## Процедура
 
## Безопасность
 
## Проверка результата
 
## Fallback

Связанные заметки

Вид графа

Обратные ссылки