| name | ai-config-authoring |
| description | Craft effective AI agent configuration — skills, rules, agents, and instructions — for any AI coding client. Use when writing or reviewing a SKILL.md, rule file, or agent definition; when deciding between a skill, rule, hook, or always-on instruction; when a config file grows past its context budget; or when a skill description fails to trigger. |
| license | Apache-2.0 |
| metadata | {"summary":"Vendor-neutral craft guide for authoring AI agent config","keywords":"authoring,skills,rules,agents,progressive-disclosure,context,descriptions,best-practices","repository":"https://github.com/grimoire-rs/grimoire"} |
AI Config Authoring
Core Principle: Context Is a Budget
Every always-loaded line competes with the user's actual task for model
attention, and attention degrades as volume grows — bloated config makes
agents ignore the instructions that matter. Pay the always-on price only
for content needed every session; defer everything else behind on-demand
loading (progressive disclosure). For each line, apply the deletion test:
would removing it cause mistakes? If not, cut it.
Budget Table
| Artifact | Budget | Cost is paid |
|---|
| Always-on instruction file | < 200 lines | Every session, every turn |
| Glob-scoped rule | < 200 lines each | Only while matching files are in play |
| Skill metadata (name + description) | ~100 tokens per skill | Every session, all skills |
| Skill body (SKILL.md) | < 500 lines / < 5k tokens | Only when the skill triggers |
| Skill bundled files | Effectively unlimited | Only when read or executed |
| Subagent | Isolated window | Separate budget; only its summary returns |
| Hook | Zero context | Never — scripts run outside the context |
The Artifact-Type Landscape
The first matching row picks the type. Full comparison — vendor support,
failure modes, migration paths — in
references/choosing-types.md.
| The content is... | Use |
|---|
| Mechanical, must happen 100% of the time, no judgment | Hook |
| Identity, commands, conventions relevant to every task | Always-on instruction file |
| A standard that applies while editing certain files | Glob-scoped rule |
| An occasional procedure or piece of domain knowledge | Skill |
| A side-effectful workflow to run only on explicit request | Manual-only skill |
| Context-heavy research, parallel work, separate privileges | Subagent |
| Something that must port across clients | Skill — the only type every client hosts |
| Logic a machine can run rather than prose to read | Hook, or a script inside a skill |
Root-as-Index Pattern
A root file is a table of contents, not a textbook: state the principle,
compress the comparison, route to depth one level down. This file is the
worked example — it stays inside the budgets it teaches, and every detail
lives in references/, loaded only when a row below matches your task.
Routing Table
Distributing Config
Config worth sharing across repositories belongs in a package manager,
not copy-paste — versioning, provenance, and an update path matter as
much for config as for code. This skill itself is distributed as an OCI
artifact via grim. To package and publish your artifact with
grim — frontmatter schemas, validation, vendor metadata — read the
companion skill grim-authoring at
../grim-authoring/SKILL.md; both ship
together in the grim-essentials bundle. If that file is missing,
install it by identifier:
grim add ghcr.io/grimoire-rs/skills/grim-authoring:0
Further Reading
- Agent Skills specification — the cross-vendor SKILL.md standard:
frontmatter constraints, directory semantics, size guidance.
- Skill authoring best practices — Anthropic's authoring guidance:
descriptions, disclosure patterns, eval-first workflow, anti-patterns.
- Effective context engineering for AI agents — the theory behind
every budget above: attention as a finite resource, just-in-time loading.
- Per-client documentation — skills install into ten clients as of 2026
(Claude Code, OpenCode, Copilot, Codex,
Cursor, Kiro, Junie, Gemini CLI,
Zed, Amp), but rules and agents each reach only about
half of them; every
references/ file carries the per-client links for
the type it covers.
