# Agent System Maintainer Version: 1.0.0 Status: ACTIVE ## Purpose Maintain the health of the repository's self-improving AI operating system. The self-improvement system must be able to do both: ```text ADD USEFUL KNOWLEDGE ``` and: ```text REMOVE STALE OR DUPLICATE KNOWLEDGE ``` Without maintenance, self-improving systems tend to accumulate: ```text too many skills duplicate rules stale project assumptions unused prompts conflicting instructions obsolete workflows ``` This skill provides deliberate cleanup. --- # 1. Trigger Conditions Use this skill: * after substantial AI-OS growth * after several new skills are added * after major project architecture changes * when agents struggle to select the right skill * when root instructions become large * when conflicting behavior appears * when skills appear duplicated * periodically when ongoing agent use justifies maintenance Do not run full maintenance after every ordinary task. --- # 2. Maintenance Flow ```text INVENTORY ↓ USAGE REVIEW ↓ DUPLICATION REVIEW ↓ CONFLICT REVIEW ↓ STALE KNOWLEDGE REVIEW ↓ SKILL HEALTH ↓ PROMPT HEALTH ↓ ROOT INSTRUCTION HEALTH ↓ PROJECT PROFILE HEALTH ↓ CLEANUP PLAN ↓ SYSTEM AUDIT ``` --- # 3. Inventory Inspect: ```text AGENTS.md CLAUDE.md .ai/AI-OS.md .ai/WORKFLOW.md .ai/PROJECT.md .ai/skills/ .ai/prompts/ .ai/templates/ .ai/state/LEARNINGS.md .ai/CHANGELOG.md ``` Determine what currently exists. --- # 4. Skill Inventory For each skill identify: ```text NAME VERSION STATUS PURPOSE TRIGGER REFERENCES KNOWN USAGE ``` Look for unclear ownership. --- # 5. Unused Skill Review Ask: ```text Has this skill actually been useful? ``` Possible statuses: ```text ACTIVE AND USED ACTIVE BUT UNCONFIRMED OBSOLETE DUPLICATE CANDIDATE ``` Do not delete a skill only because usage statistics are unavailable. Use project evidence and changelog history. --- # 6. Duplicate Skill Review Compare skills for: ```text same trigger same procedure same outputs same domain ``` If two skills overlap substantially, decide: ```text MERGE NARROW DEPRECATE ONE KEEP SEPARATE ``` Keep separate only when the distinction improves agent routing. --- # 7. Root Duplication Review Check whether `AGENTS.md` duplicates: ```text skills WORKFLOW.md AI-OS.md project documentation ``` Root instructions should contain: ```text POLICY ROUTING CORE BEHAVIOR ``` not every procedure. --- # 8. Model Adapter Review Check whether `CLAUDE.md` contains generic rules that belong in: ```text AGENTS.md ``` or project facts that belong in: ```text PROJECT.md ``` Keep model adapters thin. --- # 9. Prompt Review Inspect `.ai/prompts/`. Identify: ```text unused prompts duplicate prompts stale prompts prompts that should be skills prompts whose behavior is now in root instructions ``` Delete or deprecate low-value prompts. --- # 10. Template Review Templates should represent useful recurring structures. Check for: ```text unused templates obsolete formats duplicates project-specific content in generic templates ``` --- # 11. Learning Ledger Review Review: ```text .ai/state/LEARNINGS.md ``` Classify pending entries: ```text PROMOTE KEEP PENDING REJECT MERGE STALE ``` Do not allow old weak candidates to accumulate forever. --- # 12. Stale Project Information Compare: ```text .ai/PROJECT.md ``` against current repository evidence. Check: ```text framework runtime database deployment tests directories authentication external integrations ``` Update stale information. Do not silently preserve old architecture. --- # 13. Broken Reference Review Validate references to: ```text skills prompts templates docs scripts ``` Remove or correct broken paths. --- # 14. Version Review Check that important changes were versioned appropriately. Look for: ```text significant behavior changes without version increment deprecated skills still marked ACTIVE new skills missing changelog entries ``` --- # 15. Changelog Review Determine whether: ```text .ai/CHANGELOG.md ``` still explains meaningful AI-system evolution. Do not require excessive entries for tiny formatting changes. --- # 16. Instruction Conflict Review Search for incompatible rules. Examples: ```text always ask vs. never ask always plan vs. fast path always use skill X vs. skill X says it is optional ``` Resolve conflicts operationally. --- # 17. Routing Quality Ask: ```text Can an agent tell which skill to use? ``` If several skills could plausibly activate: ```text tighten triggers add routing rule merge skills ``` Good skill libraries are easy to navigate. --- # 18. Skill Library Size There is no ideal number. However ask: ```text Does each active skill justify its context cost? ``` A smaller high-quality library is preferable to a large noisy one. --- # 19. General vs Project Skills Classify skills as: ```text GENERAL PROJECT-SPECIFIC ``` Generic skills should remain portable. Project-specific skills may contain project domain knowledge. Do not force every skill to be universal. --- # 20. Automation Review Look for skills that repeatedly describe deterministic operations. Ask: ```text Should this become executable automation? ``` Example: Skill repeatedly says: ```text check these 12 configuration keys ``` A validation script may be better. Keep the skill as orchestration if needed, but automate reliable mechanical checks. --- # 21. Documentation Review Ensure project facts live in appropriate documentation rather than only inside AI instructions. Important knowledge should not become inaccessible to human developers. --- # 22. Simplification For each system component ask: ```text Can this be shorter without losing behavior? ``` Look for: ```text repeated definitions duplicated examples obvious rules obsolete caveats ``` Self-improvement includes compression. --- # 23. Cleanup Classification For each finding choose: ```text KEEP REVISE MOVE MERGE DEPRECATE DELETE ``` Do not perform large cleanup without understanding dependencies. --- # 24. Deprecation Before Deletion For heavily referenced skills: ```text DEPRECATE ↓ UPDATE REFERENCES ↓ VERIFY ↓ DELETE LATER ``` For unused experimental files: ```text DELETE ``` may be sufficient. Version control preserves history. --- # 25. Cleanup Safety Do not remove: ```text user-authored requirements security safeguards verification requirements project-critical workflows ``` merely to reduce file size. Simplification must preserve behavior. --- # 26. Maintenance Report Produce: ```text ## AI-OS Health ### Keep [...] ### Revise [...] ### Merge [...] ### Deprecate [...] ### Delete [...] ### Project Profile Updates [...] ### System Risks [...] ### Recommended Version Change [...] ``` For small systems, compress this. --- # 27. Apply Changes When authorized by the self-improvement rules: ```text make the smallest coherent cleanup changes ``` Then run: ```text .ai/skills/system-audit/SKILL.md ``` --- # 28. Regression After maintenance, test: ```text FAST PATH STANDARD PATH HIGH-RISK PATH SKILL ROUTING SELF-IMPROVEMENT ``` The cleaned system should behave at least as well as before. --- # 29. Maintenance Success Criteria Maintenance succeeds when: ```text agents can find guidance more easily duplicate guidance decreases stale information decreases important safeguards remain context burden decreases or remains justified no important workflow regresses ``` --- # 30. Changelog ## 1.0.0 Initial active version. Introduced: * AI-system inventory * unused skill review * duplicate skill detection * root/model adapter cleanup * prompt/template maintenance * learning-ledger cleanup * stale project-profile detection * routing review * automation opportunities * merge/deprecate/delete lifecycle