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>`.
In this repository45 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .agents/research/hooks_vendor_reports/claude.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- code-docs-cleanupSkill
- docs-instrumentSkill
- docs-planSkill
- docs-reviewSkill
- hex-architectSkill
- hex-coreSkill
- hex-discussSkill
- hex-executeSkill
- hex-finalizeSkill
- hex-initSkill
- hex-loopSkill
- hex-planSkill
- hex-retroSkill
- hex-reviewSkill
- nox-reviewSkill
- bugfixSkill
- builderSkill
- changelogSkill
- code-checkSkill
- code-docs-cleanupSkill
- commitSkill
- docs-instrumentSkill
- docs-planSkill
- docs-reviewSkill
- docsSkill
- finalizeSkill
- hex-architectSkill
- hex-coreSkill
- hex-discussSkill
- hex-executeSkill
- hex-finalizeSkill
- hex-initSkill
- hex-loopSkill
- hex-planSkill
- hex-retroSkill
- hex-reviewSkill
- meta-validate-contextSkill
- nextSkill
- nox-reviewSkill
- qa-engineerSkill
- security-auditorSkill
- upstream-refreshSkill
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
- Very specific: line 18
Keep .claude/ directory living knowledge base.
- Very specific: line 34
Use paths: scoping for rules unless truly global
- Very specific: line 36
Use progressive disclosure — SKILL.md overview, reference files for detail
- Very specific: line 37
Add disable-model-invocation: true for action skills with side effects
- Very specific: line 52
Every SKILL.md has name + description?
- Very specific: line 54
All persona skills have user-invocable: true?
- Very specific: line 59
After directory renames, glob patterns silently fail — verify with: find .
- Very specific: line 82
Check if meta-ai-config.md needs updating
- Very specific: line 104
When auditing AI config, verify .claude/rules.md reflects reality:
- Very specific: line 106
Every rule in .claude/rules/*.md has entry in .claude/rules.md
- Distinctive: line 107
Every catalog entry resolves to real file
- Very specific: line 112
Run task claude:tests — structural tests catch most drift automatically (test_catalog_covers_all_rules, test_catalog_references_resolve, …
- Distinctive: line 153
ALWAYS research online before creating AI artifacts
- Distinctive: line 154
ALWAYS run at least one research pass for domain knowledge
- Distinctive: line 155
ALWAYS check context budget impact (adding always-loaded context?)
- Distinctive: line 156
NEVER remove artifacts without checking cross-references first
- Very specific: line 157
NEVER edit settings.json hooks without testing hook script
- Distinctive: line 158
Prefer hooks over rules for enforcement (deterministic + zero context cost)
≈ “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.
Files
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].md - 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.jsonhooks without testing hook script - Prefer hooks over rules for enforcement (deterministic + zero context cost)
- Commits use
chore:prefix (per project convention)
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
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.

