CtrlK
BlogDocsLog inGet started
Tessl Logo

c4-architecture-c4-architecture

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

49

Quality

53%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/c4-architecture-c4-architecture/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

53%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body lays out a genuinely well-sequenced, concrete orchestration workflow with exact prompts, output paths, and success criteria. Its weaknesses are structural: heavy boilerplate padding, ~200 lines of prompt templates that belong in reference files, no in-flight validation for a batch operation, and a dangling reference to a nonexistent playbook plus undefined subagent types.

Suggestions

Move the four subagent prompt templates into reference files (e.g. references/code-prompt.md, references/component-prompt.md) and keep SKILL.md as an overview that links to them, fixing or removing the nonexistent resources/implementation-playbook.md reference.

Add explicit validation checkpoints between phases, e.g. after Phase 1 verify every subdirectory has a c4-code-*.md file before synthesizing, with a fix-and-retry loop for missing directories.

Delete the boilerplate 'Use this skill when'/'Do not use this skill when'/'Instructions'/'Limitations' filler sections and either wire the Configuration Options into the workflow steps or drop them.

DimensionReasoningScore

Conciseness

The core four-phase orchestration content is dense and useful, but the body carries clear filler: boilerplate sections ("Use this skill when ... Working on c4 architecture documentation workflow tasks or workflows", the generic "Instructions" bullets like "Clarify goals, constraints, and required inputs", and the "Limitations" boilerplate), a bracketed meta "Extended thinking" note, and repetition of "Create comprehensive C4 ... documentation" across each prompt. This matches anchor 3 ('mostly efficient but includes some unnecessary explanation or could be tightened'), not 2, since the padding is sectional rather than pervasive concept explanation.

3 / 5

Actionability

The workflow gives concrete, near copy-paste-ready guidance: exact Task-tool invocations with subagent types ("subagent_type=\"c4-architecture::c4-code\""), fully specified prompts with exact output paths ("Save the output as: C4-Documentation/c4-code-[directory-name].md"), an output directory tree, and a success-criteria checklist. It falls short of 5 because the four referenced subagent types are not defined anywhere in the bundle, the listed "Configuration Options" are never wired into any step, and "open resources/implementation-playbook.md" points at a file that does not exist.

4 / 5

Workflow Clarity

The four phases are clearly sequenced with bottom-up ordering ("Sort directories by depth (deepest first)") and a final success-criteria checklist, but this is a batch operation over every subdirectory and there are no in-flow validation checkpoints or fix-and-retry loops — coverage is only asserted post-hoc ("Every subdirectory has a corresponding c4-code-*.md file"). Per the judging guidelines, a batch workflow without validation steps is capped at 3.

3 / 5

Progressive Disclosure

This is a ~390-line monolithic SKILL.md in which 200+ lines of subagent prompt templates ("Analyze the code in directory: [directory_path] ... Create comprehensive C4 Code-level documentation ...") clearly belong in separate reference files, and its only reference — "If detailed examples are required, open `resources/implementation-playbook.md`" — points to a file that does not exist in the bundle (no references/, scripts/, or assets/ directories are present). That matches anchor 2 ('content that clearly belongs in separate files is inlined; or references are buried' — here, broken), and it is not 3 because the one signal for offloading detail is a dangling path.

2 / 5

Total

12

/

20

Passed

Description

53%Weight 40%Scale 1-5

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 clearly states what the skill does and occupies a distinct niche, but it reads like a domain label with a single action rather than a trigger-ready description. It lacks any 'use when' guidance and omits the natural vocabulary (diagrams, context, containers) users would actually say.

Suggestions

Add an explicit trigger clause, e.g. "Use when the user asks for architecture diagrams, a system context diagram, or C4 model documentation of a codebase."

List the concrete outputs to lift specificity, e.g. "generate Context, Container, Component, and Code level docs with Mermaid diagrams and OpenAPI specs".

Include natural synonyms such as "architecture diagram", "system context", and "visualize the codebase" alongside "C4 architecture".

DimensionReasoningScore

Specificity

The description names its domain ("C4 architecture documentation") and one concrete action ("Generate comprehensive ... documentation ... using a bottom-up analysis approach"), but stops there — it never mentions diagrams, the four C4 levels, or any of the concrete artifacts produced. This matches anchor 3 ('names domain and 1-2 concrete actions, but not comprehensive') and not anchor 4, which requires several listed specific actions.

3 / 5

Completeness

The 'what' is clear ('Generate comprehensive C4 architecture documentation for an existing repository/codebase') but there is no 'Use when...' clause or equivalent trigger guidance anywhere in the description, so per the judging guidelines completeness is capped at 3 ('clear what but when is missing'). It cannot be 4 without any explicit 'when'.

3 / 5

Trigger Term Quality

Relevant keywords are present — "C4 architecture", "documentation", "repository/codebase" — but common natural variations are missing: users would say "architecture diagram", "system context diagram", "draw the architecture", "C4 diagrams". Anchor 3 ('some relevant keywords but missing common variations or synonyms') fits; it is not 4 because coverage is not 'good' — the only natural term is the domain name itself.

3 / 5

Distinctiveness Conflict Risk

"C4 architecture documentation" carves out a fairly distinct niche — few skills target the C4 model specifically — so trigger overlap is minor (only with generic documentation/diagramming skills). Anchor 4 ('mostly distinct; minor overlap risk with closely related skills') is the best fit; it is not 5 because the description lacks distinctive trigger phrases that fully separate it from general 'document this codebase' requests.

4 / 5

Total

13

/

20

Passed

Validation

93%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

15

/

16

Passed

Repository
sickn33/agentic-awesome-skills
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.