meta-maintain-config
Use when creating or editing skills, rules, agents, or hooks under `.claude/`. Also when AI knowledge has drifted from project patterns, a new Claude Code feature lands, or syncing artifacts to current state. Modes: `create`, `audit`, `refresh`, `review`, `research <topic>`.
Install
npx skills add https://github.com/grimoire-rs/grimoire/tree/main/.claude/skills/meta-maintain-config
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 Configuration Maintenance
Keep .claude/ directory living knowledge base. Stay current with project + AI tooling best practices.
Read .claude/rules/meta-ai-config.md first — defines conventions, budget constraints, anti-patterns this skill enforces.
Modes
create — New Artifact
Discover + Research — Invoke canonical multi-agent research primitive from
/hex-plan(Phases 1-2). Spawn workers parallel:- an explorer pass (1-2): existing
.claude/patterns, conventions, cross-references, neighbors of artifact - researcher pass (1-3, split by axis): Claude Code docs (
code.claude.com/docs), domain best practices, community patterns for artifact topic
Persist substantial findings as
.agents/research/research_[topic].mdfor reuse. See/hex-plan"Research as a Reusable Primitive".- an explorer pass (1-2): existing
Draft — Follow
meta-ai-config.mdconventions:- Respect context budget (<200 lines rules, <500 lines skills)
- Use
paths:scoping for rules unless truly global - Skills: write description as "what + when to use" (max 1024 chars)
- Use progressive disclosure — SKILL.md overview, reference files for detail
- Add
disable-model-invocation: truefor action skills with side effects
Integrate — Update AGENTS.md tables, meta-rule inventory
Validate — Run audit checks (see below)
audit — Check All Artifacts
Context budget audit:
- AGENTS.md under 280 lines?
- Each global rule under 200 lines?
- Count global rules — too many degrades performance
- Skill descriptions total within 2% context budget?
Structural audit:
- Every SKILL.md has
name+description? - No
allowed-toolsin skill frontmatter? - All persona skills have
user-invocable: true? - Hook scripts executable?
Dead glob audit:
- For each scoped rule, do
paths:patterns match existing files? - After directory renames, glob patterns silently fail — verify with:
find . -path "pattern" | head -1
Cross-reference audit:
- Rules referencing other rules → targets exist?
- Skills referencing rules → correct filenames?
- Agents referencing rules → still valid?
Duplication audit:
- Same instruction in AGENTS.md AND rule? (single source of truth)
- Same domain knowledge in skill AND rule? (skill for on-demand, rule for always-on)
refresh — Sync AI Knowledge with Codebase
Detect drift — explorer pass:
- Public types in
subsystem-*.mdstill exist in code? - New modules/crates lacking subsystem rules?
- Error variants, trait names, method signatures still match?
- CLI commands changed (new flags, subcommands)?
deny.toml/.licenserc.tomlchanged?
- Public types in
Research updates — researcher pass:
- Claude Code docs for new features (hooks, frontmatter, agents)
- New best practices in Rust, async, testing, security
- Check if
meta-ai-config.mdneeds updating
Update stale artifacts — Read current code, update with accurate info, preserve structure
Self-update — Check if this skill (
meta-maintain-config) ormeta-ai-config.mdoutdated per research findings. Update them too.Validate — Run
auditmode
review — AI Config Quality Review
Review recent changes to .claude/ for quality:
- Context budget — Change increase always-loaded context? Justified?
- Scoping — Could this global rule be path-scoped instead?
- Progressive disclosure — SKILL.md body under 500 lines? Move details to reference files?
- Description quality — Skill description specific enough for auto-discovery?
- Anti-patterns — Check against 8 anti-patterns in
meta-ai-config.md - Consistency — Change follow existing artifact conventions?
- Reusability — Hook more appropriate than rule? (deterministic + zero context cost)
catalog-sync — Catalog Drift Review
When auditing AI config, verify .claude/rules.md reflects reality:
- Every rule in
.claude/rules/*.mdhas entry in.claude/rules.md - Every catalog entry resolves to real file
AGENTS.mdstill links to catalog (CLAUDE.mdonly forwards via@AGENTS.md)- "By concern" table reflects current development axes (add rows for new concerns; remove for retired)
- "By auto-load path" table matches actual
paths:frontmatter in each rule file
Run task claude:tests — structural tests catch most drift automatically (test_catalog_covers_all_rules, test_catalog_references_resolve, test_context_md_points_to_catalog). Manual review catches semantic drift (e.g., new concern worth catalog row even if no test complains).
research — Deep-Dive Topic
Invoke canonical multi-agent research primitive from /hex-plan (Phases 1-2). No reinvent.
Spawn workers parallel — per
/hex-planPhase 2 axis-splitting:- researchers × 2-3, split by axis:
- Tooling axis — Claude Code / AI tooling best practices
- Domain axis — Rust patterns, OCI spec, cargo-deny, etc.
- Community axis — how other projects handle this
- explorer (optional) — ground external findings in existing
.claude/artifacts
- researchers × 2-3, split by axis:
Synthesize → Actionable guidance. Persist as
.agents/research/research_[topic].mdApply → Update relevant artifacts
Refresh Targets
| Artifact | What goes stale | Refresh trigger |
|---|---|---|
subsystem-*.md rules |
Types, paths, signatures, error variants | After refactors, new modules |
quality-rust.md (+ other quality-*.md) |
Language anti-patterns, async conventions, 2026 updates | After edition/release updates, new tooling |
arch-principles.md |
Design principles, ADR index, code style conventions | After new patterns, new modules |
| Persona skills | Implementation patterns, fixtures, commands | After new commands, workflows |
deps |
License allowlist, tool versions | After deny.toml changes |
AGENTS.md |
Build commands, env vars, layout | After new crates, env vars |
meta-ai-config.md |
Conventions, budget numbers, anti-patterns | After Claude Code releases |
| This skill | Modes, workflow, refresh targets | After Claude Code releases |
Maintenance Schedule
| Frequency | Action |
|---|---|
| Every feature branch | audit before merging AI config changes |
| Monthly | refresh to detect drift |
| On Claude Code update | research "Claude Code new features" then self-update |
| On new tool integration | create for tool's skill/rule, then audit |
| When something feels off | review recent changes |
Constraints
- ALWAYS research online before creating AI artifacts
- ALWAYS run at least one research pass for domain knowledge
- ALWAYS check context budget impact (adding always-loaded context?)
- NEVER remove artifacts without checking cross-references first
- NEVER edit
settings.jsonhooks without testing hook script - Prefer hooks over rules for enforcement (deterministic + zero context cost)
- Commits use
chore:prefix (per project convention)
Files (grimoire)
-
SKILL.md 7.5 KB
--- name: meta-maintain-config description: 'Use when creating or editing skills, rules, agents, or hooks under `.claude/`. Also when AI knowledge has drifted from project patterns, a new Claude Code feature lands, or syncing artifacts to current state. Modes: `create`, `audit`, `refresh`, `review`, `research <topic>`.' user-invocable: true argument-hint: "create | audit | refresh | review | research topic" disable-model-invocation: true triggers: - "maintain the config" - "update the rules" - "update the skills" - "ai config drift" - "add a skill" - "edit the agent" --- # AI Configuration Maintenance Keep `.claude/` directory living knowledge base. Stay current with project + AI tooling best practices. **Read `.claude/rules/meta-ai-config.md` first** — defines conventions, budget constraints, anti-patterns this skill enforces. ## Modes ### `create` — New Artifact 1. **Discover + Research** — Invoke canonical multi-agent research primitive from `/hex-plan` (Phases 1-2). Spawn workers parallel: - an explorer pass (1-2): existing `.claude/` patterns, conventions, cross-references, neighbors of artifact - researcher pass (1-3, split by axis): Claude Code docs (`code.claude.com/docs`), domain best practices, community patterns for artifact topic Persist substantial findings as `.agents/research/research_[topic].md` for reuse. See `/hex-plan` "Research as a Reusable Primitive". 2. **Draft** — Follow `meta-ai-config.md` conventions: - Respect context budget (<200 lines rules, <500 lines skills) - Use `paths:` scoping for rules unless truly global - Skills: write description as "what + when to use" (max 1024 chars) - Use progressive disclosure — SKILL.md overview, reference files for detail - Add `disable-model-invocation: true` for action skills with side effects 3. **Integrate** — Update AGENTS.md tables, meta-rule inventory 4. **Validate** — Run audit checks (see below) ### `audit` — Check All Artifacts **Context budget audit:** - AGENTS.md under 280 lines? - Each global rule under 200 lines? - Count global rules — too many degrades performance - Skill descriptions total within 2% context budget? **Structural audit:** - Every SKILL.md has `name` + `description`? - No `allowed-tools` in skill frontmatter? - All persona skills have `user-invocable: true`? - Hook scripts executable? **Dead glob audit:** - For each scoped rule, do `paths:` patterns match existing files? - After directory renames, glob patterns silently fail — verify with: `find . -path "pattern" | head -1` **Cross-reference audit:** - Rules referencing other rules → targets exist? - Skills referencing rules → correct filenames? - Agents referencing rules → still valid? **Duplication audit:** - Same instruction in AGENTS.md AND rule? (single source of truth) - Same domain knowledge in skill AND rule? (skill for on-demand, rule for always-on) ### `refresh` — Sync AI Knowledge with Codebase 1. **Detect drift** — explorer pass: - Public types in `subsystem-*.md` still exist in code? - New modules/crates lacking subsystem rules? - Error variants, trait names, method signatures still match? - CLI commands changed (new flags, subcommands)? - `deny.toml` / `.licenserc.toml` changed? 2. **Research updates** — researcher pass: - Claude Code docs for new features (hooks, frontmatter, agents) - New best practices in Rust, async, testing, security - Check if `meta-ai-config.md` needs updating 3. **Update stale artifacts** — Read current code, update with accurate info, preserve structure 4. **Self-update** — Check if this skill (`meta-maintain-config`) or `meta-ai-config.md` outdated per research findings. Update them too. 5. **Validate** — Run `audit` mode ### `review` — AI Config Quality Review Review recent changes to `.claude/` for quality: 1. **Context budget** — Change increase always-loaded context? Justified? 2. **Scoping** — Could this global rule be path-scoped instead? 3. **Progressive disclosure** — SKILL.md body under 500 lines? Move details to reference files? 4. **Description quality** — Skill description specific enough for auto-discovery? 5. **Anti-patterns** — Check against 8 anti-patterns in `meta-ai-config.md` 6. **Consistency** — Change follow existing artifact conventions? 7. **Reusability** — Hook more appropriate than rule? (deterministic + zero context cost) ### `catalog-sync` — Catalog Drift Review When auditing AI config, verify `.claude/rules.md` reflects reality: 1. Every rule in `.claude/rules/*.md` has entry in `.claude/rules.md` 2. Every catalog entry resolves to real file 3. `AGENTS.md` still links to catalog (`CLAUDE.md` only forwards via `@AGENTS.md`) 4. "By concern" table reflects current development axes (add rows for new concerns; remove for retired) 5. "By auto-load path" table matches actual `paths:` frontmatter in each rule file Run `task claude:tests` — structural tests catch most drift automatically (`test_catalog_covers_all_rules`, `test_catalog_references_resolve`, `test_context_md_points_to_catalog`). Manual review catches semantic drift (e.g., new concern worth catalog row even if no test complains). ### `research` — Deep-Dive Topic Invoke canonical multi-agent research primitive from `/hex-plan` (Phases 1-2). No reinvent. 1. **Spawn workers parallel** — per `/hex-plan` Phase 2 axis-splitting: - researchers × 2-3, split by axis: - *Tooling axis* — Claude Code / AI tooling best practices - *Domain axis* — Rust patterns, OCI spec, cargo-deny, etc. - *Community axis* — how other projects handle this - explorer (optional) — ground external findings in existing `.claude/` artifacts 2. **Synthesize** → Actionable guidance. Persist as `.agents/research/research_[topic].md` 3. **Apply** → Update relevant artifacts ## Refresh Targets | Artifact | What goes stale | Refresh trigger | |----------|----------------|-----------------| | `subsystem-*.md` rules | Types, paths, signatures, error variants | After refactors, new modules | | `quality-rust.md` (+ other `quality-*.md`) | Language anti-patterns, async conventions, 2026 updates | After edition/release updates, new tooling | | `arch-principles.md` | Design principles, ADR index, code style conventions | After new patterns, new modules | | Persona skills | Implementation patterns, fixtures, commands | After new commands, workflows | | `deps` | License allowlist, tool versions | After deny.toml changes | | `AGENTS.md` | Build commands, env vars, layout | After new crates, env vars | | `meta-ai-config.md` | Conventions, budget numbers, anti-patterns | After Claude Code releases | | **This skill** | Modes, workflow, refresh targets | After Claude Code releases | ## Maintenance Schedule | Frequency | Action | |-----------|--------| | Every feature branch | `audit` before merging AI config changes | | Monthly | `refresh` to detect drift | | On Claude Code update | `research "Claude Code new features"` then self-update | | On new tool integration | `create` for tool's skill/rule, then `audit` | | When something feels off | `review` recent changes | ## Constraints - ALWAYS research online before creating AI artifacts - ALWAYS run at least one research pass for domain knowledge - ALWAYS check context budget impact (adding always-loaded context?) - NEVER remove artifacts without checking cross-references first - NEVER edit `settings.json` hooks without testing hook script - Prefer hooks over rules for enforcement (deterministic + zero context cost) - Commits use `chore:` prefix (per project convention)
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.