Схема фронтматтера
Справочное руководство по структуре блока YAML-фронтматтера, обязательным ключам по классам и правилам их применения валидаторами для всех классов артефактов.
Каноническая справка по YAML-фронтматтеру для каждого класса артефактов. Сводка в разделе «Conventions» файла
CLAUDE.md— это встроенное объявление; JSON Schema по классам вsrc/apothem/schemas/(схемы навыков и команд сadditionalProperties: falseотклоняют неизвестные ключи; схемы агентов, output-стилей и планов задаютadditionalProperties: true) — машиночитаемый контракт, и при любом расхождении приоритет у него. Эта страница — указатель обязательных ключей, аartifact-schema.mdxсодержит шаблоны и разобранные примеры по классам; обе страницы — человекочитаемые проекции этих схем.
1. Форма блока фронтматтера
Каждый артефакт несёт YAML-фронтматтер в начале, ограниченный строками ---. В файлах семейства Markdown фронтматтер — это первое содержимое файла, а каноническая строка заголовка SPDX согласно site/content/docs/reference/authorship-header.mdx следует за закрывающим ---.
Ключи команд записываются в kebab-case. Ключи навыков записываются в kebab-case, за исключением userInvocable — написания в camelCase, которое использует исходный корпус (установка Claude Code переименовывает его в user-invocable). Установка для Claude Code и плагин также переносят ключи, специфичные для Apothem (version, updated, archetype, portability), навыка или команды в замыкающую карту metadata: из строк в кавычках, в этом фиксированном порядке, поскольку Claude Code игнорирует неизвестные ключи верхнего уровня, а стандарт Agent Skills хранит дополнительные ключи в metadata; исходные файлы и все остальные окружения оставляют их на верхнем уровне, за исключением общих папок навыков уровня пользователя (~/.agents/skills/ и папок ~/.codebuddy/skills/, ~/.kiro/skills/ и ~/.trae/skills/), которые сворачивают их таким же образом. Ключи правил и делегированных исполнителей записываются в camelCase, как показано в таблице обязательных ключей в разделе 2. Скалярные значения указываются либо без кавычек, либо в двойных кавычках; строковые значения, содержащие двоеточия, знаки решётки или другие символы, значимые для YAML, заключаются в кавычки.
2. Обязательные поля по классам
Набор обязательных ключей зависит от класса артефакта. Авторитетную форму обеспечивают scripts/dev/validate_ecosystem.py и JSON Schema по классам в каталоге src/apothem/schemas/. У классов помощников, навыков, команд, output-стилей и планов есть по одному файлу схемы, они перечислены ниже; у классов CLAUDE.md и правил схем нет, их ключи проверяет validate_ecosystem.py. Файлов планов в таблице ниже нет; их ключи перечислены в разделе Дисциплина планов.
src/apothem/schemas/agent.schema.json
src/apothem/schemas/skill.schema.json
src/apothem/schemas/command.schema.json
src/apothem/schemas/output-style.schema.json
src/apothem/schemas/plan.schema.json| Класс | Обязательные ключи |
|---|---|
CLAUDE.md (корневая конфигурация) | name, version, updated, description, scope, portability |
Правила (src/apothem/rules/*.md) | name, description, pathFilter, alwaysApply |
Команды (src/apothem/commands/*.md) | name, version, updated, description, argument-hint, disable-model-invocation, portability, allowed-tools |
Помощники, они же делегированные исполнители (src/apothem/agents/*.md) | name, version, updated, description, tools (необязательный: помощник, который его опускает, наследует все инструменты; чтобы дать помощнику, перечисляющему tools, MCP-сервер, укажите этот сервер в ключе профиля agent_mcp_servers), disallowedTools, maxTurns, effort |
Навыки (src/apothem/skills/*/SKILL.md) | name, version, updated, description, archetype, userInvocable, disable-model-invocation, allowed-tools; установка для Claude Code и плагин, а также общие папки навыков уровня пользователя, переименовывают userInvocable в user-invocable, а схема требует, чтобы каждый навык нёс ровно одно из двух написаний, но не оба сразу; установка Qwen Code записывает allowed-tools как список allowedTools — ключ и форму, которые читает Qwen Code |
Output-стили (src/apothem/output-styles/*.md) | name, description; каждый поставляемый стиль также задаёт keep-coding-instructions: true, чтобы Claude Code сохранял свои инструкции по программной инженерии |
Схемы по классам в src/apothem/schemas/ содержат полный набор ограничений, включая ограничения типа, формата, enum и шаблона, а также ограничения длины: description навыка или команды — не более 1024 символов, это предел Agent Skills.
3. Валидаторы
scripts/dev/validate_ecosystem.py обходит дерево артефактов, применяет приведённые выше наборы обязательных ключей и сообщает [FAIL] для любого артефакта, в котором отсутствует обязательное поле. Проверка frontmatter-grep при каждой записи, расположенная в src/apothem/conformity/frontmatter_grep.py, обеспечивает ту же форму на границах хука PreToolUse для Write/Edit.
Соглашения об именовании
Предписывает имена файлов в kebab-case, формат ключей frontmatter, именование веток с префиксами типа и семантику числовых префиксов для упорядоченных последовательностей артефактов.
Соглашения по Markdown
Стандартизация диалекта Markdown, структуры заголовков, объявлений языка в блоках кода, форматов внутренних ссылок, заголовков авторства и контроля со стороны валидаторов.