c4-architecture-c4-architecture

Generate comprehensive C4 architecture documentation for an existing repository/codebase using a bottom-up analysis approach.

Quality

42%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/c4-architecture-c4-architecture/SKILL.md

The canonical home for this skill is c4-architecture-c4-architecture in sickn33/agentic-awesome-skills

Quality

Content

27%Scale 1-3

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 extremely verbose workflow description that reads more like a design document than an actionable skill. The inline prompt templates for each C4 level agent massively inflate the token cost, the content explains concepts Claude already understands, and critical validation/feedback loops between phases are missing. The referenced implementation playbook doesn't exist in the bundle, undermining progressive disclosure.

Suggestions

Extract the detailed subagent prompt templates into separate bundle files (e.g., prompts/c4-code-prompt.md, prompts/c4-component-prompt.md) and reference them from the main skill, reducing the SKILL.md to a concise workflow overview.

Remove the extended thinking block, the generic 'Use this skill when/Do not use this skill when' sections, the generic 'Instructions' section, and the C4 model explanation - these add no value for Claude.

Add explicit validation checkpoints between phases: e.g., 'Verify all c4-code-*.md files exist before proceeding to Phase 2' with a concrete check (list files, count vs expected).

Either provide the referenced `resources/implementation-playbook.md` bundle file or remove the reference to avoid broken links.

Dimension	Reasoning	Score
Conciseness	Extremely verbose at ~300+ lines. Contains extensive boilerplate Claude already knows (what C4 model is, basic concepts), redundant sections (the 'Use this skill when' / 'Do not use this skill when' adds nothing), and the massive prompt templates inline are repetitive. The extended thinking block at the top is pure waste. Much of this could be condensed to 1/3 the size.	1 / 3
Actionability	Provides structured prompts for subagents and clear output file naming conventions, which is somewhat actionable. However, the actual instructions are more descriptive templates than executable steps - there's no concrete code for directory traversal, no actual commands to run, and the 'Example Usage' is just a single slash command with no real demonstration of inputs/outputs.	2 / 3
Workflow Clarity	The four-phase workflow is clearly sequenced with logical dependencies (bottom-up through C4 levels), and the success criteria checklist is helpful. 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	The skill references `resources/implementation-playbook.md` but no bundle files are provided, making this a broken reference. The entire content is a monolithic wall of text with massive inline prompt templates that should be in separate files. The detailed prompt structures for each subagent type bloat the main file enormously and would be better as referenced templates.	1 / 3
	Total	6 / 12 Passed

Description

57%Scale 1-3

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 specificity of actions and completeness. It lacks an explicit 'Use when...' clause and could benefit from listing specific deliverables (e.g., context, container, component diagrams) and more natural trigger terms users might employ.

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 the structure of a codebase.'

List specific concrete actions/outputs such as 'Generates context diagrams, container diagrams, component diagrams, and code-level documentation following the C4 model.'

Include additional natural trigger terms like 'architecture diagram', 'system diagram', 'C4 model', 'software architecture visualization', 'PlantUML' to improve keyword coverage.

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 via bottom-up analysis) but lacks an explicit 'Use when...' clause specifying when Claude should select this skill. The 'when' is only implied.	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

Validation

90%

Warnings & errors only

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: popey/claude-code-skills
Path: skills/c4-architecture-c4-architecture/SKILL.md
Commit: a5a6601

Reviewed: 20 hours ago

Table of Contents

Discovery Implementation Validation

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.