Claude Skill

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

LLM Mart · 0 points · 0 views 13 listing impressions 0 install-command copies

#agents #context

Download grimoire-rs-grimoire-catalog_skills_ai-config-authoring-dddf811.zip · 33 KB

Install

skills CLI npx skills add https://github.com/grimoire-rs/grimoire/tree/main/catalog/skills/ai-config-authoring
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install grimoire-rs-grimoire@llmmart
Git 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

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.

No comments yet.

Reviews (0)

No reviews yet.