maintain-designs
Skill for maintaining clear, DRY, and easy-to-navigate design documents for architect agents.
When & Why to Use This Skill
This Claude skill is designed to streamline the creation and maintenance of high-quality software architecture documentation. By enforcing DRY (Don't Repeat Yourself) principles and a structured workflow—including inventory, consolidation, and pruning—it ensures that design documents remain clear, skimmable, and easy to navigate for both human developers and AI architect agents, effectively preventing documentation rot and architectural drift.
Use Cases
- Consolidating fragmented design notes: Automatically identifying overlapping technical topics and merging them into a single, authoritative canonical document.
- Technical debt reduction in documentation: Pruning obsolete references, deleting redundant pages, and replacing duplicates with concise stubs to maintain a lean knowledge base.
- Improving AI Agent context: Structuring design docs to be high-level and skimmable, making it easier for AI architect agents to parse and understand system structures without being overwhelmed by low-level code.
- Knowledge discovery: Creating and maintaining a minimal top-level index that allows team members to quickly find specific architectural themes and specifications.
| name | maintain-designs |
|---|---|
| description | Skill for maintaining clear, DRY, and easy-to-navigate design documents for architect agents. |
Objects
Clarity, easy discovery, minimal redundancy, low upkeep designs with clear canonicals and minimal code.
Principles
One topic per page; one canonical per topic. Prefer deletion with consolidation instead of duplicates. Keep pages skimmable. Stay high-level and include minimal code.
Workflow
Inventory (quick)
List all docs with a one-line summary and note overlaps. No metadata beyond that. Cluster by theme Group loosely (e.g., UI, backend, parsing, patterns, specs). Keep flexible. Choose canonicals For overlapping topics, pick the clearest/most current as the canonical.
Consolidate
Pull unique, still-relevant bits into the canonical. Rewrite for skim: Title, TL;DR, When to use, How, Gotchas, Links. Split only if a page becomes unwieldy.
Prune
Delete or replace overlaps with a one-line stub linking to the canonical. Move rough-but-useful notes to a lightweight WIP area; drop the rest. Delete obsolete docs and references. Design docs should never reference plans.
Organize
Arrange under a small set of theme folders or keep flat. Use nesting sparingly and only when it clearly aids navigation.
Index
Add or update a minimal top-level index (and optional per-theme) with curated links and one-liners. Remove drift and new duplicates.
Done when
No obvious duplicates. Everything is discoverable from a minimal index. Docs are short, skimmable, and easy to maintain.