SKILL.md
Arch Lens
Seven-step interactive architectural review. An Explore sub-agent navigates the codebase the way a developer would — the confusion, file-bouncing, and untestable seams it encounters are the findings. No checklists, no rigid heuristics.
Deep module: small interface surface hiding a large, self-contained implementation.
Lets callers test at the boundary. Lets AI agents reason without reading internals.
Quick start
- If a path argument is given, scope to that directory; otherwise whole repo
- Load
${CLAUDESKILLDIR}/references/WORKFLOW.md— full step-by-step instructions - Load
${CLAUDESKILLDIR}/references/DETECTION-PATTERNS.md - Load
${CLAUDESKILLDIR}/references/INTERFACE-DESIGN.md - Load
${CLAUDESKILLDIR}/references/RFC-FILE-FORMAT.md - Execute the seven steps in WORKFLOW.md
Workflows
| Step | What happens | Requires user input |
|---|---|---|
| 1. Explore | Spawn Explore sub-agent; navigate organically; record friction | — |
| 2. Candidates | Synthesise friction into clusters; present max 8 with full context | — |
| 3. Pick | User selects a cluster and directs the angle | wait |
| 4. Frame | Problem statement, dependency category, blast radius, test boundary today | — |
| 5. Design | Spawn 3–4 parallel sub-agents with competing interface designs | — |
| 6. Choose | User picks interface or accepts recommendation | wait |
| 7. RFC file | Write arch-rfcs-YYYY-MM-DD.md to project root |
— |
Full prompt text, cluster format, and step detail: see WORKFLOW.md.
Behavioural rules
- Explore agent friction observations are primary evidence — never override with static analysis
- Never propose interface designs before Step 5
- Never advance past Steps 3 or 6 without a user response
- Every RFC must include exact
file:linereferences and a before/after illustration - Name every dependency category explicitly — it determines the testing strategy
- Rank clusters: testability impact first, then cognitive load, then interface stability
Advanced features
- Full workflow detail and Explore agent prompt:
${CLAUDESKILLDIR}/references/WORKFLOW.md - Friction vocabulary and dependency categories:
${CLAUDESKILLDIR}/references/DETECTION-PATTERNS.md - Sub-agent brief template and design constraints:
${CLAUDESKILLDIR}/references/INTERFACE-DESIGN.md - RFC action file format and complete example:
${CLAUDESKILLDIR}/references/RFC-FILE-FORMAT.md