c4-code

Expert C4 Code-level documentation specialist. Analyzes code directories to create comprehensive C4 code-level documentation including function signatures, arguments, dependencies, and code structure.

Quality

55%

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-code/SKILL.md

Quality

Content

43%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 skill's strength is its library of concrete Mermaid diagram templates with a clear paradigm-selection table, which gives Claude real scaffolding for C4 code-level output. Its weaknesses are the near-empty abstract instruction section, the absence of any sequenced analysis workflow or validation step, and a dangling reference to a nonexistent resources/implementation-playbook.md, compounded by broken code fences (stray ```` and ``` lines) that corrupt the markdown structure.

Suggestions

Replace the vague Instructions bullets with a sequenced workflow: list/scan the target directory, extract signatures and dependencies per code element, populate the template sections, then validate (e.g., confirm every file:line location resolves and each Mermaid block renders) before presenting output.

Fix the progressive-disclosure failure: either add resources/implementation-playbook.md (ideally under references/) with the detailed examples, or remove the pointer; consider moving the three large Mermaid examples into that reference file and keeping only the selection table inline.

Cut the generic boilerplate ('Use/Do not use this skill when' placeholder sections, the C4-model explainer note) and repair the broken code fences (the stray 4-backtick fence and the orphan ``` lines before the Notes and Limitations sections) so the markdown parses cleanly.

Dimension	Reasoning	Score
Conciseness	The diagram templates and selection table earn their tokens, but there is padded generic boilerplate — 'Clarify goals, constraints, and required inputs. Apply relevant best practices and validate outcomes', the placeholder 'Do not use this skill when' section, and a C4-model explainer ('Most teams find system context and container diagrams sufficient') that Claude already knows. Not 4 because several sections could be cut outright; not 2 because the core diagram examples are dense and useful rather than verbose.	3 / 5
Actionability	Concrete artifacts exist — three complete Mermaid diagram templates (classDiagram, two flowcharts) and a paradigm-to-diagram selection table — but the actual instructions are abstract ('Apply relevant best practices and validate outcomes'), the output sections are unfilled placeholder skeletons, and the pointer 'open resources/implementation-playbook.md' targets a file that does not exist in the bundle. Not 4 because there are no concrete analysis steps or a worked example; not 2 because the diagram templates are copy-paste ready and the selection table is decisively concrete.	3 / 5
Workflow Clarity	The Instructions section offers only a rough, unordered abstraction ('Clarify goals... Apply relevant best practices... Provide actionable steps and verification') with no sequence for analyzing a directory, no checkpoints, and no validation of outputs such as file:line references. This matches anchor 2 (rough sequence, many gaps, validation absent); not 1 because some process guidance and an output structure do exist; not 3 because even implicit checkpoints are missing. No destructive/batch cap applies since this is a documentation task.	2 / 5
Progressive Disclosure	The body is well-sectioned with clear headers, but roughly 120 lines of Mermaid examples are inlined where a references file would fit, and the sole external pointer ('open resources/implementation-playbook.md') is dangling — no resources/, references/, scripts/, or assets/ directory exists in the bundle. Not 4 because the one reference present is broken and the inline example bulk belongs in a separate file; not 2 because section structure and navigation within SKILL.md itself are decent.	3 / 5
	Total	11 / 20 Passed

Description

66%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 is concrete and appropriately third-person, clearly stating what the skill produces at the C4 code level. Its main weakness is the complete absence of a 'when to use' trigger clause, which both caps completeness and limits trigger-term coverage. Adding an explicit 'Use when...' sentence with natural synonyms would lift it substantially.

Suggestions

Append a trigger clause such as: 'Use when creating C4 code-level (Class) documentation, documenting function signatures and dependencies in a source directory, or when the user mentions C4 code diagrams or code-structure documentation.'

Add natural trigger synonyms users would actually say — 'diagrams', 'Mermaid', 'map the code', 'code structure' — to improve trigger_term_quality.

Note in the description that this is the most granular C4 level, to reduce overlap risk with sibling context/container/component skills.

Dimension	Reasoning	Score
Specificity	Uses third person and lists several concrete actions — 'Analyzes code directories to create comprehensive C4 code-level documentation including function signatures, arguments, dependencies, and code structure' — naming concrete deliverables. Not 5 because the actions largely restate 'create documentation' and omit diagramming/multi-paradigm coverage that the body actually delivers; not 3 because more than 1-2 specific actions are explicitly named.	4 / 5
Completeness	The 'what' is clear (analyzes code directories and produces C4 code-level documentation with signatures, arguments, dependencies, structure), but there is no 'Use when...' clause or equivalent trigger guidance anywhere in the description. Per the rubric guideline, a missing 'when' clause caps completeness at 3, and it is not 2 because the 'what' is concrete and multi-part.	3 / 5
Trigger Term Quality	Contains good niche keywords a user would plausibly say: 'C4 Code-level documentation', 'code directories', 'function signatures', 'dependencies', 'code structure'. Not 5 because common variations like 'diagrams', 'Mermaid', 'map the codebase', or language-specific terms are missing; not 3 because the key niche term 'C4' plus several natural phrases are present.	4 / 5
Distinctiveness Conflict Risk	'C4 Code-level documentation' carves out a fairly distinct niche and 'Code-level' separates it from other C4 levels. Not 5 because it doesn't explicitly distinguish itself from sibling C4 skills (context/container/component), creating minor overlap risk within the C4 family; not 3 because the level qualifier and concrete deliverables make it more than 'somewhat specific'.	4 / 5
	Total	15 / 20 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
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-code/SKILL.md
Commit: 7b534bc

Reviewed: 21 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.