code-documentation

Use this skill when the user requests to generate, create, or improve documentation for code, APIs, libraries, repositories, or software projects. Supports README generation, API reference documentation, inline code comments, architecture documentation, changelog generation, and developer guides. Trigger on requests like "document this code", "create a README", "generate API docs", "write developer guide", or when analyzing codebases for documentation purposes.

Quality

78%

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

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, actionable workflow with strong templates and validation checklists, but it is a monolithic ~410-line document. It restates conventions Claude already knows (per-language docstring formats, generic writing principles) and keeps all reference material inline instead of splitting it into bundle files.

Suggestions

Move the language-specific inline documentation examples (Python/TypeScript/Go/Rust/Java sections) into a references/ file (e.g. references/inline-formats.md) and keep only the existing conventions summary table in SKILL.md.

Extract the README, API-reference, and architecture templates into references/templates.md, linked from the generation steps, to cut the main file's token footprint substantially.

Delete or drastically compress the 'Writing Principles' list (active voice, present tense, show-don't-tell) — this is generic writing knowledge Claude already applies, adding pure token cost.

Replace the nonexistent `read_file` command in Phase 1.2 with the actual file-reading tool invocation so the analysis commands are literally executable.

Dimension	Reasoning	Score
Conciseness	The ~410-line body is mostly efficient (Phase 1 discovery tables, QA checklists), but several sections restate knowledge Claude already has: full docstring/JSDoc/GoDoc examples in three languages and a generic "Writing Principles" style guide ("Active voice", "Present tense", "Show, don't tell"). This fits anchor 3 — could be tightened — rather than anchor 2 because the templates do carry format-specification value, and not anchor 4 because the redundant sections are more than minor.	3 / 5
Actionability	Provides concrete, mostly executable guidance: bash commands for codebase analysis, full README/API-reference templates, parameter tables, and QA checklists. Anchor 4 rather than 5 because the templates are placeholder skeletons ("[Key feature 1 — brief description]") and Phase 1.2 mixes real commands with a nonexistent `read_file` tool.	4 / 5
Workflow Clarity	Clear three-phase sequence (Analyze → Generate → QA) with explicit checkpoints in Phase 3 (completeness checklist and cross-reference validation), fitting anchor 4. Not anchor 5 because there is no explicit fix-and-retry feedback loop after validation checks fail; not anchor 3 because validation checkpoints are genuinely present, not implicit.	4 / 5
Progressive Disclosure	No bundle files exist and everything is inlined in one long SKILL.md — per-language inline doc conventions, full README and API templates, and the style guide all clearly belong in separate reference files. Internal section structure is good, matching anchor 3 (well-organized but content that should be separate is inline) rather than anchor 4, which would require bulk content to be offloaded to clearly signaled references.	3 / 5
	Total	14 / 20 Passed

Description

92%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 strong: it names concrete capabilities comprehensively, provides natural trigger phrases, and explicitly states both what the skill does and when to use it. The only gap is modest synonym coverage in trigger terms (e.g., docstrings, JSDoc, "write docs").

Dimension	Reasoning	Score
Specificity	"Supports README generation, API reference documentation, inline code comments, architecture documentation, changelog generation, and developer guides" lists multiple specific concrete actions with comprehensive coverage of the code-documentation domain. It exceeds anchor 4 because there are no minor gaps in the action list.	5 / 5
Completeness	Explicitly answers both "what" ("Supports README generation, API reference documentation, inline code comments...") and "when" ("Use this skill when the user requests... Trigger on requests like...") with concrete trigger phrases. This matches anchor 5; anchor 4 would require the 'when' clause to be less explicit, which it is not.	5 / 5
Trigger Term Quality	Includes natural phrases users would actually say — "document this code", "create a README", "generate API docs", "write developer guide" — but misses common variations such as "write docs", "docstrings", "JSDoc", or "user guide". Good coverage with a few natural terms missing fits anchor 4, not the comprehensive synonym/file-extension coverage of anchor 5.	4 / 5
Distinctiveness Conflict Risk	"Documentation for code, APIs, libraries, repositories, or software projects" with triggers like "document this code" and "create a README" defines a clear niche with minimal overlap risk against generic writing or research skills. Matches anchor 5 rather than anchor 4 because the triggers are specific enough to disambiguate.	5 / 5
	Total	19 / 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
relative_links	Relative link issues: 2 missing	Warning

	Total	15 / 16 Passed

Repository: bytedance/deer-flow
Path: skills/public/code-documentation/SKILL.md
Commit: ee44d1e

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