agentleFS
grimoire-rsgrimoire-rs/grimoire/.claude/skills/meta-maintain-config/SKILL.md

meta-maintain-config

Skill15 starsChanged 20 days agoApache-2.0View on GitHub

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>`.

The file

Show its rules and text

We split this skill into the rules it gives an agent

18 rules. About 0 are common, 6 are distinctive, and 12 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 12

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Keep .claude/ directory living knowledge base.

    line 18
  2. Very specific:

    Use paths: scoping for rules unless truly global

    line 34
  3. Very specific:

    Use progressive disclosure — SKILL.md overview, reference files for detail

    line 36
  4. Very specific:

    Add disable-model-invocation: true for action skills with side effects

    line 37
  5. Very specific:

    Every SKILL.md has name + description?

    line 52
  6. Very specific:

    All persona skills have user-invocable: true?

    line 54
  7. Very specific:

    After directory renames, glob patterns silently fail — verify with: find .

    line 59
  8. Very specific:

    Check if meta-ai-config.md needs updating

    line 82
  9. Very specific:

    When auditing AI config, verify .claude/rules.md reflects reality:

    line 104
  10. Very specific:

    Every rule in .claude/rules/*.md has entry in .claude/rules.md

    line 106
  11. Distinctive:

    Every catalog entry resolves to real file

    line 107
  12. Very specific:

    Run task claude:tests — structural tests catch most drift automatically (test_catalog_covers_all_rules, test_catalog_references_resolve, …

    line 112
  13. Distinctive:

    ALWAYS research online before creating AI artifacts

    line 153
  14. Distinctive:

    ALWAYS run at least one research pass for domain knowledge

    line 154
  15. Distinctive:

    ALWAYS check context budget impact (adding always-loaded context?)

    line 155
  16. Distinctive:

    NEVER remove artifacts without checking cross-references first

    line 156
  17. Very specific:

    NEVER edit settings.json hooks without testing hook script

    line 157
  18. Distinctive:

    Prefer hooks over rules for enforcement (deterministic + zero context cost)

    line 158

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

ArtifactWhat goes staleRefresh trigger
subsystem-*.md rulesTypes, paths, signatures, error variantsAfter refactors, new modules
quality-rust.md (+ other quality-*.md)Language anti-patterns, async conventions, 2026 updatesAfter edition/release updates, new tooling
arch-principles.mdDesign principles, ADR index, code style conventionsAfter new patterns, new modules
Persona skillsImplementation patterns, fixtures, commandsAfter new commands, workflows
depsLicense allowlist, tool versionsAfter deny.toml changes
AGENTS.mdBuild commands, env vars, layoutAfter new crates, env vars
meta-ai-config.mdConventions, budget numbers, anti-patternsAfter Claude Code releases
This skillModes, workflow, refresh targetsAfter Claude Code releases

Maintenance Schedule

FrequencyAction
Every feature branchaudit before merging AI config changes
Monthlyrefresh to detect drift
On Claude Code updateresearch "Claude Code new features" then self-update
On new tool integrationcreate for tool's skill/rule, then audit
When something feels offreview 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)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.