c4-architecture-c4-architecture
Generate comprehensive C4 architecture documentation for an existing repository/codebase using a bottom-up analysis approach.
64
46%
Does it follow best practices?
Impact
98%
1.60xAverage score across 3 eval scenarios
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 domain (C4 architecture documentation) but falls short on specificity of actions and completeness. It lacks an explicit 'Use when...' clause and doesn't enumerate the specific outputs or actions (e.g., generating context, container, component diagrams). The niche is well-defined enough to avoid conflicts with other skills.
Suggestions
Add a 'Use when...' clause with trigger terms like 'architecture diagram', 'C4 model', 'system documentation', 'software architecture', 'codebase analysis'.
List specific concrete actions such as 'generates context diagrams, container diagrams, component diagrams, and code-level documentation from existing source code'.
Include common keyword variations users might say, such as 'architecture overview', 'system design docs', 'PlantUML', or 'Structurizr'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (C4 architecture documentation) and the general 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 | Describes what it does (generate C4 architecture documentation using bottom-up analysis) but lacks an explicit 'Use when...' clause specifying when Claude should select this skill. | 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', 'software architecture', or 'PlantUML'. | 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
35%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 overly verbose workflow description that suffers from inlining too much detail. The four-phase structure is logical and well-sequenced, but the lack of validation checkpoints between phases and the absence of error recovery mechanisms weaken the workflow. The content would benefit significantly from extracting the large prompt templates into separate files and adding explicit verification steps between phases.
Suggestions
Remove the '[Extended thinking: ...]' block, generic instructions section ('Clarify goals, constraints...'), and the 'Use this skill when / Do not use this skill when' boilerplate - these waste tokens on things Claude already knows.
Add explicit validation checkpoints between phases, e.g., 'Verify all c4-code-*.md files exist before proceeding to Phase 2' with a concrete verification step or command.
Extract the large subagent prompt templates into separate resource files (e.g., resources/code-agent-prompt.md) and reference them from the main skill to dramatically reduce inline verbosity.
Add error recovery guidance: what to do if a subagent fails, if a directory has no analyzable code, or if component boundaries are ambiguous.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~300+ lines. Contains extensive explanations Claude already knows (what C4 model is, what personas are, what OpenAPI specs are). The massive prompt templates embedded inline could be referenced from separate files. The '[Extended thinking: ...]' block and generic instructions like 'Clarify goals, constraints, and required inputs' add no value. | 1 / 3 |
Actionability | Provides structured prompts for subagents and clear output file naming conventions, which is somewhat actionable. However, the actual execution relies on Task tool calls with subagent types that aren't fully explained, there's no executable code for directory discovery/sorting, and the prompts are templates with placeholders rather than concrete executable examples. | 2 / 3 |
Workflow Clarity | The four phases are clearly sequenced with a logical bottom-up progression, and success criteria serve as a checklist. However, there are no validation checkpoints between phases - no step to verify Phase 1 completeness before starting Phase 2, no error recovery if a subagent fails, and no feedback loops for fixing issues in generated documentation. | 2 / 3 |
Progressive Disclosure | References `resources/implementation-playbook.md` for detailed examples, which is good. However, the massive prompt templates for each phase are inlined when they could be in separate resource files. The skill is a monolithic wall of text that would benefit greatly from splitting the detailed subagent prompts into referenced files. | 2 / 3 |
Total | 7 / 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 | |
- Repository
- sickn33/antigravity-awesome-skills
- Commit
e18e63c
- Reviewed
Table of Contents
Is this your skill?
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.