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
| Read... |
...when |
| references/choosing-types.md |
Picking an artifact type, or migrating content between types |
| references/skill-design.md |
Writing or restructuring a SKILL.md and its bundled files |
| references/rule-design.md |
Writing always-on instructions or glob-scoped rules |
| references/agent-design.md |
Defining a subagent or designing delegation between agents |
| references/descriptions.md |
A skill or agent fails to trigger, or before finalizing any description |
| references/guardrails.md |
You want a copy-pastable always-on enforcement card |
| references/checklist.md |
Reviewing a config package before publishing or installing it |
| references/updating.md |
Maintaining this guide itself — re-research protocol and search terms |
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 # installs by default
# fresh project (no grimoire.toml yet): run `grim init` first
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 — the clients surveyed throughout this skill
(Claude Code, OpenCode, Copilot, Codex,
Cursor, Kiro, Junie, Gemini CLI,
Zed, Amp) all host skills, but rules and agents each reach
only about half of them. Newer clients keep arriving skills-first, and a
second wave of them (Antigravity, Cline, Droid,
Goose, Warp, OpenClaw, Kilo) held
that pattern without exception — which is why a skill is the portable
default. Every
references/ file carries the per-client links for the
type it covers.
1---2name: ai-config-authoring3description: 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.4license: Apache-2.05---67# AI Config Authoring89## Core Principle: Context Is a Budget1011Every always-loaded line competes with the user's actual task for model12attention, and attention degrades as volume grows — bloated config makes13agents ignore the instructions that matter. Pay the always-on price only14for content needed every session; defer everything else behind on-demand15loading (progressive disclosure). For each line, apply the deletion test:16would removing it cause mistakes? If not, cut it.1718## Budget Table1920| Artifact | Budget | Cost is paid |21|---|---|---|22| Always-on instruction file | < 200 lines | Every session, every turn |23| Glob-scoped rule | < 200 lines each | Only while matching files are in play |24| Skill metadata (name + description) | ~100 tokens per skill | Every session, all skills |25| Skill body (SKILL.md) | < 500 lines / < 5k tokens | Only when the skill triggers |26| Skill bundled files | Effectively unlimited | Only when read or executed |27| Subagent | Isolated window | Separate budget; only its summary returns |28| Hook | Zero context | Never — scripts run outside the context |2930## The Artifact-Type Landscape3132The first matching row picks the type. Full comparison — vendor support,33failure modes, migration paths — in34[references/choosing-types.md](references/choosing-types.md).3536| The content is... | Use |37|---|---|38| Mechanical, must happen 100% of the time, no judgment | Hook |39| Identity, commands, conventions relevant to every task | Always-on instruction file |40| A standard that applies while editing certain files | Glob-scoped rule |41| An occasional procedure or piece of domain knowledge | Skill |42| A side-effectful workflow to run only on explicit request | Manual-only skill |43| Context-heavy research, parallel work, separate privileges | Subagent |44| Something that must port across clients | Skill — the only type every client hosts |45| Logic a machine can run rather than prose to read | Hook, or a script inside a skill |4647## Root-as-Index Pattern4849A root file is a table of contents, not a textbook: state the principle,50compress the comparison, route to depth one level down. This file is the51worked example — it stays inside the budgets it teaches, and every detail52lives in `references/`, loaded only when a row below matches your task.5354## Routing Table5556| Read... | ...when |57|---|---|58| [references/choosing-types.md](references/choosing-types.md) | Picking an artifact type, or migrating content between types |59| [references/skill-design.md](references/skill-design.md) | Writing or restructuring a SKILL.md and its bundled files |60| [references/rule-design.md](references/rule-design.md) | Writing always-on instructions or glob-scoped rules |61| [references/agent-design.md](references/agent-design.md) | Defining a subagent or designing delegation between agents |62| [references/descriptions.md](references/descriptions.md) | A skill or agent fails to trigger, or before finalizing any description |63| [references/guardrails.md](references/guardrails.md) | You want a copy-pastable always-on enforcement card |64| [references/checklist.md](references/checklist.md) | Reviewing a config package before publishing or installing it |65| [references/updating.md](references/updating.md) | Maintaining this guide itself — re-research protocol and search terms |6667## Distributing Config6869Config worth sharing across repositories belongs in a package manager,70not copy-paste — versioning, provenance, and an update path matter as71much for config as for code. This skill itself is distributed as an OCI72artifact via [grim][grimoire]. To package and publish your artifact with73grim — frontmatter schemas, validation, vendor metadata — read the74companion skill `grim-authoring` at75[`../grim-authoring/SKILL.md`](../grim-authoring/SKILL.md); both ship76together in the `grim-essentials` bundle. If that file is missing,77install it by identifier:7879```sh80grim add ghcr.io/grimoire-rs/skills/grim-authoring:0 # installs by default81# fresh project (no grimoire.toml yet): run `grim init` first82```8384## Further Reading8586- [Agent Skills specification][spec] — the cross-vendor SKILL.md standard:87 frontmatter constraints, directory semantics, size guidance.88- [Skill authoring best practices][bp] — Anthropic's authoring guidance:89 descriptions, disclosure patterns, eval-first workflow, anti-patterns.90- [Effective context engineering for AI agents][ctx] — the theory behind91 every budget above: attention as a finite resource, just-in-time loading.92- Per-client documentation — the clients surveyed throughout this skill93 ([Claude Code][cc], [OpenCode][oc], [Copilot][cop], [Codex][cx],94 [Cursor][cur], [Kiro][kiro], [Junie][junie], [Gemini CLI][gem],95 [Zed][zed], [Amp][amp]) all host skills, but rules and agents each reach96 only about half of them. Newer clients keep arriving skills-first, and a97 second wave of them ([Antigravity][ag], [Cline][cline], [Droid][droid],98 [Goose][goose], [Warp][warp], [OpenClaw][openclaw], [Kilo][kilo]) held99 that pattern without exception — which is why a skill is the portable100 default. Every `references/` file carries the per-client links for the101 type it covers.102103[grimoire]: https://github.com/grimoire-rs/grimoire104[spec]: https://agentskills.io/specification105[bp]: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices106[ctx]: https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents107[cc]: https://code.claude.com/docs/en/skills108[oc]: https://opencode.ai/docs/skills/109[cop]: https://docs.github.com/en/copilot/concepts/agents/about-agent-skills110[cx]: https://developers.openai.com/codex/skills111[cur]: https://cursor.com112[kiro]: https://kiro.dev113[junie]: https://www.jetbrains.com/junie/114[gem]: https://geminicli.com115[zed]: https://zed.dev116[amp]: https://ampcode.com117[ag]: https://antigravity.google118[cline]: https://cline.bot119[droid]: https://factory.ai120[goose]: https://block.github.io/goose121[warp]: https://warp.dev122[openclaw]: https://github.com/openclaw/openclaw123[kilo]: https://kilo.ai
grimoire-rs