CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

c4-architecture-c4-architecture

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

Quality

69%

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

63%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 delivers a well-sequenced, genuinely actionable four-phase workflow with concrete outputs and validation checkpoints, but it is long and monolithic: boilerplate filler inflates token cost and the inlined prompt templates preclude a lean overview-plus-references structure. Tightening the filler and splitting phase prompts into reference files would materially improve it.

Suggestions

Cut the circular 'Use this skill when / Do not use this skill when' bullets and the generic 'Instructions' section ('Clarify goals... Apply relevant best practices') — they add tokens without task-specific value, addressing the conciseness gap.

Move the four phase prompt templates into references/ files (e.g., references/code-level-prompt.md, references/container-prompt.md) and keep SKILL.md as a concise overview that links to them, improving progressive disclosure.

Add explicit validate-and-retry feedback loops (e.g., what to do when a delegation output fails the success-criteria checklist, or when a diagram does not render) to push workflow clarity from good to complete.

DimensionReasoningScore

Conciseness

The bulk is operational and task-specific (output paths, filename conventions, API-spec guidance), but filler is present: the circular 'Use this skill when... c4 architecture documentation workflow tasks or workflows' bullets, the generic 'Clarify goals, constraints, and required inputs / Apply relevant best practices' instructions, and fully scaffolded prompt templates ('Function name, parameters (with types), return type...') that assume too little of Claude. This fits 'mostly efficient but includes some unnecessary explanation or could be tightened' rather than the noticeably-padded level 2.

3 / 5

Actionability

Guidance is concrete for an instruction-only skill: exact output filenames ('C4-Documentation/c4-code-[directory-name].md'), collision-free path mapping rules, configuration options with defaults, a full output tree, and copy-paste-ready delegation prompts. Minor gaps remain — e.g., 'Use codebase search to identify all subdirectories' gives no specific command — so it is 'mostly executable guidance with minor gaps' rather than fully copy-paste ready.

4 / 5

Workflow Clarity

The four phases are clearly sequenced (bottom-up, deepest-first, incremental synthesis) with checkpoints such as 'Before writing, record repository/head, audience, system boundary and files actually inspected', 'check links and IDs', the Mermaid render-or-fallback rule, and a success-criteria checklist. Validation is present for this batch operation so the cap-at-3 rule does not apply, but explicit validate-fix-retry feedback loops are largely absent, keeping it below the level-5 anchor.

4 / 5

Progressive Disclosure

The body is well-sectioned with clear phase headers and no broken or nested references, but it is a ~400-line monolith: the four large phase prompt templates and detailed API-spec structure are prime candidates for separate reference files, leaving SKILL.md as an overview. This matches 'some structure... content that should be separate is inline' rather than level 2, since the internal structure is good, not minimal.

3 / 5

Total

14

/

20

Passed

Description

61%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 anchors it to a recognizable niche (C4 architecture), but it stops short of listing concrete deliverables and entirely lacks a 'Use when...' trigger clause. Adding explicit usage triggers and one or two concrete outputs would lift both completeness and specificity.

Suggestions

Append a trigger clause such as: 'Use when the user asks for C4 diagrams, system context/container diagrams, or architecture documentation of a repository or codebase.' This directly addresses the missing 'when' that caps completeness at 3.

Enumerate the concrete deliverables (e.g., 'creates code, component, container, and context-level diagrams plus OpenAPI specs') so the description lists several specific actions instead of one generic 'generate documentation' action.

Include common user synonyms such as 'C4 model', 'diagrams', and 'architecture overview' to broaden natural trigger-term coverage.

DimensionReasoningScore

Specificity

The description names the domain ("C4 architecture documentation") and one concrete action ("Generate comprehensive C4 architecture documentation... using a bottom-up analysis approach"), but does not enumerate several specific deliverables such as context/container/component/code diagram levels or API specs. This matches the anchor 'names domain and 1-2 concrete actions, but not comprehensive' rather than the level above, which requires a list of several 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 explicit trigger guidance, which caps completeness at 3 per the judging guidelines. It is not a 2 because the 'what' is explicit and specific.

3 / 5

Trigger Term Quality

Natural user phrasings are present: "C4 architecture", "architecture documentation", "repository", "codebase". Common variations like "diagrams", "C4 model", or "visualize architecture" are missing, so it fits 'good keyword coverage; a few natural terms missing' rather than the comprehensive synonym-level coverage of the top anchor.

4 / 5

Distinctiveness Conflict Risk

"C4 architecture documentation" is a distinct niche with low conflict risk against unrelated skills, though the generic framing ("documentation for an existing repository/codebase") leaves minor overlap risk with general code-documentation or diagramming skills. It is mostly distinct (anchor 4) rather than a fully distinct niche with trigger phrases (anchor 5).

4 / 5

Total

14

/

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

Path

skills/c4-architecture-c4-architecture/SKILL.md

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.