Generate comprehensive C4 architecture documentation for an existing repository/codebase using a bottom-up analysis approach.
42
42%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/c4-architecture-c4-architecture/SKILL.mdQuality
Discovery
57%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description identifies a clear and distinctive niche (C4 architecture documentation) but falls short on completeness by lacking explicit trigger guidance ('Use when...') and on specificity by not enumerating the concrete actions or outputs involved. Adding trigger terms and more specific capabilities would significantly improve skill selection accuracy.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user asks for architecture diagrams, C4 models, system documentation, or wants to visualize codebase structure.'
List specific concrete actions such as 'Generates context, container, component, and code-level diagrams following the C4 model framework.'
Include additional natural trigger terms users might say, such as 'architecture diagram', 'system overview', 'C4 model', 'software architecture', or 'Structurizr'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | It names the domain (C4 architecture documentation) and the approach (bottom-up analysis), but doesn't list specific concrete actions like generating context diagrams, container diagrams, component diagrams, or code-level diagrams. | 2 / 3 |
Completeness | It answers 'what' (generate C4 architecture documentation using bottom-up analysis) but lacks an explicit 'Use when...' clause or equivalent trigger guidance, which caps this at 2 per the rubric. | 2 / 3 |
Trigger Term Quality | Includes some relevant keywords like 'C4 architecture', 'documentation', 'repository', 'codebase', but misses common user variations like 'architecture diagram', 'system diagram', 'C4 model', 'structurizr', or 'software architecture'. | 2 / 3 |
Distinctiveness Conflict Risk | C4 architecture documentation is a clear, specific niche that is unlikely to conflict with other skills. The combination of 'C4', 'architecture documentation', and 'bottom-up analysis' creates a distinct identity. | 3 / 3 |
Total | 9 / 12 Passed |
Implementation
27%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is a comprehensive but excessively verbose workflow description that would benefit significantly from restructuring. The core idea—bottom-up C4 documentation generation using subagents—is sound, but the execution suffers from massive inline prompt templates, missing validation steps, broken file references, and unnecessary boilerplate sections that waste context window tokens without adding actionable value.
Suggestions
Reduce content by 50%+: Remove the extended thinking block, generic 'Use this skill when/Do not use this skill when' sections, the generic Instructions section, and the Limitations boilerplate. Trim prompt templates to essential structure only, removing obvious details Claude can infer.
Add explicit validation checkpoints between phases: e.g., 'Verify all c4-code-*.md files exist before proceeding to Phase 2' with a concrete check command or listing step, and include error recovery instructions if a subagent produces incomplete output.
Split the four phase prompt templates into separate referenced files (e.g., phases/code-level.md, phases/component-level.md) and keep SKILL.md as a concise overview with phase summaries and navigation links.
Either provide the referenced `resources/implementation-playbook.md` bundle file or remove the broken reference.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~300+ lines. Contains extensive boilerplate Claude already knows (what C4 model is, basic concepts), redundant sections ('Use this skill when/Do not use this skill when' adds no value), and massive prompt templates that repeat structural patterns. The extended thinking block, generic instructions section, and limitations section are all unnecessary padding. | 1 / 3 |
Actionability | Provides structured prompts for subagents and a clear phase-based approach with specific file naming conventions and output structures. However, the guidance is more template/prompt-oriented than executable—there are no actual code snippets for directory traversal, filtering, or file generation. The Task tool invocations describe what to ask subagents but lack concrete implementation details like how to discover directories or handle edge cases. | 2 / 3 |
Workflow Clarity | The four-phase workflow is clearly sequenced (Code → Component → Container → Context) with explicit dependencies between phases. However, there are no validation checkpoints or feedback loops—no step to verify that code-level docs are complete before starting component synthesis, no error recovery if a subagent fails, and no verification that generated documentation is consistent or correct. The success criteria checklist exists but is post-hoc, not integrated into the workflow. | 2 / 3 |
Progressive Disclosure | References `resources/implementation-playbook.md` but no bundle files are provided, making this a broken reference. The entire skill is a monolithic wall of text with no meaningful content split across files. All four phases with their full prompt templates are inlined, when they could be separated into individual phase files or reference documents. | 1 / 3 |
Total | 6 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
fb2efea
Table of Contents
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.