sharaf/software-architecture-audit
Run an evidence-grounded software architecture audit workflow that builds a repo brief, selects single-auditor or specialist-panel mode, inspects boundary, layering, dependency, composition, cohesion, and testability risks, writes required finding blocks, and sequences incremental refactors. Use when asked for an architecture audit, architecture review, repo-structure review, software architecture report, audit_report.md, structural issue findings, or specialist-panel synthesis across multi-module systems.
100
100%
Does it follow best practices?
Impact
100%
1.85xAverage score across 3 eval scenarios
Passed
No known issues
Quality
Discovery
100%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is an excellent skill description that thoroughly covers what the skill does with specific workflow steps and concrete outputs, while also providing a comprehensive 'Use when' clause with multiple natural trigger terms. The description is detailed without being padded, uses proper third-person voice, and carves out a very distinct niche that would be easy to differentiate from other skills.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: builds a repo brief, selects auditor mode, inspects boundary/layering/dependency/composition/cohesion/testability risks, writes finding blocks, and sequences incremental refactors. Very detailed and actionable. | 3 / 3 |
Completeness | Clearly answers both 'what' (the full workflow from repo brief through finding blocks and refactor sequencing) and 'when' (explicit 'Use when...' clause listing multiple trigger scenarios). Both halves are well-developed. | 3 / 3 |
Trigger Term Quality | Includes strong natural trigger terms: 'architecture audit', 'architecture review', 'repo-structure review', 'software architecture report', 'audit_report.md', 'structural issue findings', 'specialist-panel synthesis', 'multi-module systems'. Good coverage of terms users would naturally use. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive with a clear niche: architecture auditing with specific modes (single-auditor vs specialist-panel), specific risk categories (boundary, layering, dependency, etc.), and specific outputs (finding blocks, audit_report.md). Unlikely to conflict with general code review or other skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
100%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a high-quality skill that efficiently communicates a complex multi-step architecture audit workflow. It strikes an excellent balance between providing enough inline detail (format anchors, output contract, workflow summary) and delegating deeper content to well-signaled reference files. The content is concise, actionable, and well-structured with clear mode selection criteria and explicit output requirements.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is lean and well-structured. It avoids explaining what architecture audits are or how Claude should think about code. Every section serves a distinct purpose—mode selection, workflow summary, format anchors, output contract—without redundancy or padding. | 3 / 3 |
Actionability | The skill provides concrete format anchors with exact markdown templates for finding blocks and improvement sequence items, a specific ordered workflow, explicit mode selection criteria, and a mandatory section list for the output. The references to external files for full templates and guardrails are appropriate delegation rather than vagueness. | 3 / 3 |
Workflow Clarity | The 5-step workflow summary is clearly sequenced with logical dependencies (build brief → select mode → inspect → collapse findings → sequence repairs). Step 5 explicitly handles ambiguity via 'Open Evidence Gaps' rather than guessing, which serves as a validation/feedback mechanism. The guardrails reference adds completion checks. | 3 / 3 |
Progressive Disclosure | The SKILL.md serves as a clear overview with a well-organized reference table pointing to three one-level-deep files (audit-workflow.md, report-templates.md, guardrails-and-success.md), each with a clear purpose description. The inline content provides enough context (format anchors, workflow summary, output contract) to be useful without requiring immediate reference lookup. | 3 / 3 |
Total | 12 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
Reviewed
Table of Contents