7.8KB
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:
ADD USEFUL KNOWLEDGE
and:
REMOVE STALE OR DUPLICATE KNOWLEDGE
Without maintenance, self-improving systems tend to accumulate:
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
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:
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:
NAME
VERSION
STATUS
PURPOSE
TRIGGER
REFERENCES
KNOWN USAGE
Look for unclear ownership.
5. Unused Skill Review
Ask:
Has this skill actually been useful?
Possible statuses:
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:
same trigger
same procedure
same outputs
same domain
If two skills overlap substantially, decide:
MERGE
NARROW
DEPRECATE ONE
KEEP SEPARATE
Keep separate only when the distinction improves agent routing.
7. Root Duplication Review
Check whether AGENTS.md duplicates:
skills
WORKFLOW.md
AI-OS.md
project documentation
Root instructions should contain:
POLICY
ROUTING
CORE BEHAVIOR
not every procedure.
8. Model Adapter Review
Check whether CLAUDE.md contains generic rules that belong in:
AGENTS.md
or project facts that belong in:
PROJECT.md
Keep model adapters thin.
9. Prompt Review
Inspect .ai/prompts/.
Identify:
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:
unused templates
obsolete formats
duplicates
project-specific content in generic templates
11. Learning Ledger Review
Review:
.ai/state/LEARNINGS.md
Classify pending entries:
PROMOTE
KEEP PENDING
REJECT
MERGE
STALE
Do not allow old weak candidates to accumulate forever.
12. Stale Project Information
Compare:
.ai/PROJECT.md
against current repository evidence.
Check:
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:
skills
prompts
templates
docs
scripts
Remove or correct broken paths.
14. Version Review
Check that important changes were versioned appropriately.
Look for:
significant behavior changes without version increment
deprecated skills still marked ACTIVE
new skills missing changelog entries
15. Changelog Review
Determine whether:
.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:
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:
Can an agent tell which skill to use?
If several skills could plausibly activate:
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:
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:
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:
Should this become executable automation?
Example:
Skill repeatedly says:
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:
Can this be shorter without losing behavior?
Look for:
repeated definitions
duplicated examples
obvious rules
obsolete caveats
Self-improvement includes compression.
23. Cleanup Classification
For each finding choose:
KEEP
REVISE
MOVE
MERGE
DEPRECATE
DELETE
Do not perform large cleanup without understanding dependencies.
24. Deprecation Before Deletion
For heavily referenced skills:
DEPRECATE
↓
UPDATE REFERENCES
↓
VERIFY
↓
DELETE LATER
For unused experimental files:
DELETE
may be sufficient.
Version control preserves history.
25. Cleanup Safety
Do not remove:
user-authored requirements
security safeguards
verification requirements
project-critical workflows
merely to reduce file size.
Simplification must preserve behavior.
26. Maintenance Report
Produce:
## 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:
make the smallest coherent cleanup changes
Then run:
.ai/skills/system-audit/SKILL.md
28. Regression
After maintenance, test:
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:
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