Skema Frontmatter
Panduan referensi untuk struktur blok frontmatter YAML, kunci wajib per kelas, dan aturan penegakan validator di seluruh kelas artefak.
Referensi kanonik untuk frontmatter YAML pada setiap kelas artefak. Ringkasan di
CLAUDE.mdpada bagian Konvensi merupakan deklarasi inline; JSON Schema per kelas disrc/apothem/schemas/(additionalProperties: falsepada skema skill dan command menolak kunci yang tidak dikenal; skema agent, output-style, dan plan menetapkanadditionalProperties: true) adalah kontrak yang terbaca mesin dan menang jika ada ketidaksesuaian. Halaman ini adalah indeks kunci wajib, danartifact-schema.mdxmemuat templat dan contoh lengkap per kelas — keduanya adalah proyeksi yang dapat dibaca manusia dari skema-skema tersebut.
1. Bentuk Blok Frontmatter
Setiap artefak membawa frontmatter YAML di bagian kepala, yang dibatasi oleh baris ---. Pada berkas keluarga Markdown, frontmatter adalah konten pertama berkas, dan baris header SPDX kanonik sesuai site/content/docs/reference/authorship-header.mdx mengikuti --- penutup.
Kunci command menggunakan kebab-case. Kunci skill menggunakan kebab-case kecuali userInvocable, ejaan camelCase yang dipakai korpus sumber (instalasi Claude Code mengganti namanya menjadi user-invocable). Instalasi Claude Code dan plugin juga memindahkan kunci khusus Apothem (version, updated, archetype, portability) dari sebuah skill atau command ke bawah peta metadata: di bagian akhir yang berisi string bertanda kutip, dalam urutan tetap tersebut, karena Claude Code mengabaikan kunci tingkat atas yang tidak dikenal dan standar Agent Skills menyimpan kunci tambahan di metadata; berkas sumber dan setiap harness lain mempertahankannya di tingkat atas, kecuali folder skill tingkat pengguna bersama (~/.agents/skills/ serta folder ~/.codebuddy/skills/, ~/.kiro/skills/, dan ~/.trae/skills/), yang melipatnya dengan cara yang sama. Kunci aturan dan pekerja terdelegasi menggunakan camelCase, sebagaimana tercantum dalam tabel kunci wajib di bagian 2. Nilai skalar ditulis polos atau dengan tanda kutip ganda; nilai string yang mengandung titik dua, tanda pagar, atau karakter YAML penting lainnya diberi tanda kutip.
2. Field Wajib per Kelas
Himpunan kunci wajib bervariasi menurut kelas artefak. Bentuk otoritatifnya ditegakkan oleh scripts/dev/validate_ecosystem.py dan JSON Schema per kelas di bawah direktori src/apothem/schemas/. Kelas pembantu, skill, command, output-style, dan plan masing-masing memiliki satu berkas skema, yang tercantum di bawah; kelas CLAUDE.md dan aturan tidak memilikinya, dan validate_ecosystem.py memeriksa kunci kedua kelas itu. Berkas plan tidak ada dalam tabel di bawah; kuncinya tercantum di Disiplin plan.
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| Kelas | Kunci wajib |
|---|---|
CLAUDE.md (konfigurasi root) | name, version, updated, description, scope, portability |
Aturan (src/apothem/rules/*.md) | name, description, pathFilter, alwaysApply |
Command (src/apothem/commands/*.md) | name, version, updated, description, argument-hint, disable-model-invocation, portability, allowed-tools |
Pembantu, disebut juga pekerja terdelegasi (src/apothem/agents/*.md) | name, version, updated, description, tools (opsional: pembantu yang menghilangkannya mewarisi setiap tool; untuk memberikan server MCP kepada pembantu yang mencantumkan tools, sebutkan server tersebut di kunci agent_mcp_servers pada profil), disallowedTools, maxTurns, effort |
Skill (src/apothem/skills/*/SKILL.md) | name, version, updated, description, archetype, userInvocable, disable-model-invocation, allowed-tools; instalasi Claude Code dan plugin, serta folder skill tingkat pengguna bersama, mengganti nama userInvocable menjadi user-invocable, dan skema mewajibkan setiap skill membawa tepat salah satu dari kedua ejaan tersebut, tidak pernah keduanya; instalasi Qwen Code menulis allowed-tools sebagai daftar allowedTools, yaitu kunci dan bentuk yang dibaca Qwen Code |
Output-style (src/apothem/output-styles/*.md) | name, description; setiap gaya yang dikirimkan juga menetapkan keep-coding-instructions: true agar Claude Code mempertahankan instruksi rekayasa perangkat lunaknya |
Skema per kelas di src/apothem/schemas/ memuat himpunan batasan lengkap, termasuk batasan tipe, format, enum, dan pola, serta batas panjang: description sebuah skill atau command paling banyak 1.024 karakter, yaitu batas Agent Skills.
3. Validator
scripts/dev/validate_ecosystem.py menelusuri pohon artefak, menerapkan himpunan kunci wajib di atas, dan melaporkan [FAIL] untuk setiap artefak yang tidak memiliki field wajib. frontmatter-grep per penulisan di src/apothem/conformity/frontmatter_grep.py menegakkan bentuk yang sama pada batas hook PreToolUse Write/Edit.
Konvensi penamaan
Menetapkan nama berkas kebab-case, format kunci frontmatter, penamaan branch dengan prefiks tipe, dan semantik prefiks numerik untuk urutan artefak terurut.
Konvensi Markdown
Menstandarkan varian Markdown, struktur heading, deklarasi pagar kode, format tautan internal, header kepengarangan, dan penegakan oleh validator.