ai-config-authoring
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 pas
#agents #context
Install
npx skills add https://github.com/grimoire-rs/grimoire/tree/main/catalog/skills/ai-config-authoring
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install grimoire-rs-grimoire@llmmart
git clone https://github.com/grimoire-rs/grimoire.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole grimoire-rs/grimoire collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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 |
Every row above is packageable — grim distributes skills, rules, subagents, MCP registrations, and now hooks as artifact kinds. That changes distribution, never portability: a hook still needs a lifecycle surface in the client to be written at all, so it reaches a narrow set (four clients today) where a skill reaches all of them. Details in references/choosing-types.md.
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
Teams that reach people through a plugin marketplace rather than a package manager: only skills and MCP servers survive every plugin format, so write marketplace-bound content as a skill (choosing-types.md).
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.
Files (grimoire)
-
references
-
agent-design.md 9.4 KB
Loading… -
checklist.md 3.4 KB
Loading… -
choosing-types.md 18.3 KB
Loading… -
descriptions.md 4.9 KB
Loading… -
guardrails.md 2.8 KB
Loading… -
rule-design.md 10.4 KB
Loading… -
skill-design.md 10.1 KB
Loading… -
updating.md 6.3 KB
Loading…
-
-
SKILL.md 7.2 KB
--- 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](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 | Every row above is *packageable* — grim distributes skills, rules, subagents, MCP registrations, and now hooks as artifact kinds. That changes distribution, never portability: a hook still needs a lifecycle surface in the client to be written at all, so it reaches a narrow set (four clients today) where a skill reaches all of them. Details in [references/choosing-types.md](references/choosing-types.md). ## 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](references/choosing-types.md) | Picking an artifact type, or migrating content between types | | [references/skill-design.md](references/skill-design.md) | Writing or restructuring a SKILL.md and its bundled files | | [references/rule-design.md](references/rule-design.md) | Writing always-on instructions or glob-scoped rules | | [references/agent-design.md](references/agent-design.md) | Defining a subagent or designing delegation between agents | | [references/descriptions.md](references/descriptions.md) | A skill or agent fails to trigger, or before finalizing any description | | [references/guardrails.md](references/guardrails.md) | You want a copy-pastable always-on enforcement card | | [references/checklist.md](references/checklist.md) | Reviewing a config package before publishing or installing it | | [references/updating.md](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][grimoire]. To package and publish your artifact with grim — frontmatter schemas, validation, vendor metadata — read the companion skill `grim-authoring` at [`../grim-authoring/SKILL.md`](../grim-authoring/SKILL.md); both ship together in the `grim-essentials` bundle. If that file is missing, install it by identifier: ```sh grim add ghcr.io/grimoire-rs/skills/grim-authoring:0 # installs by default # fresh project (no grimoire.toml yet): run `grim init` first ``` Teams that reach people through a plugin marketplace rather than a package manager: only skills and MCP servers survive every plugin format, so write marketplace-bound content as a skill ([choosing-types.md](references/choosing-types.md)). ## Further Reading - [Agent Skills specification][spec] — the cross-vendor SKILL.md standard: frontmatter constraints, directory semantics, size guidance. - [Skill authoring best practices][bp] — Anthropic's authoring guidance: descriptions, disclosure patterns, eval-first workflow, anti-patterns. - [Effective context engineering for AI agents][ctx] — 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][cc], [OpenCode][oc], [Copilot][cop], [Codex][cx], [Cursor][cur], [Kiro][kiro], [Junie][junie], [Gemini CLI][gem], [Zed][zed], [Amp][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][ag], [Cline][cline], [Droid][droid], [Goose][goose], [Warp][warp], [OpenClaw][openclaw], [Kilo][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. [grimoire]: https://github.com/grimoire-rs/grimoire [spec]: https://agentskills.io/specification [bp]: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices [ctx]: https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents [cc]: https://code.claude.com/docs/en/skills [oc]: https://opencode.ai/docs/skills/ [cop]: https://docs.github.com/en/copilot/concepts/agents/about-agent-skills [cx]: https://developers.openai.com/codex/skills [cur]: https://cursor.com [kiro]: https://kiro.dev [junie]: https://www.jetbrains.com/junie/ [gem]: https://geminicli.com [zed]: https://zed.dev [amp]: https://ampcode.com [ag]: https://antigravity.google [cline]: https://cline.bot [droid]: https://factory.ai [goose]: https://goose-docs.ai [warp]: https://warp.dev [openclaw]: https://github.com/openclaw/openclaw [kilo]: https://kilo.ai
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.