code-documentation

Writing effective code documentation - API docs, README files, inline comments, and technical guides. Use for documenting codebases, APIs, or writing developer guides.

Quality

73%

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

Quality

Content

71%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.

A well-organized reference-style skill with concrete, executable templates across README, API, inline comments, and architecture docs. It is largely actionable and reasonably concise, but inlines substantial reference material in one file (no progressive disclosure to separate files) and lacks an explicit doc-validation/review checkpoint despite flagging stale docs as harmful.

Suggestions

Move the bulky templates (full README, OpenAPI/Swagger schema, ADR) into one-level-deep reference files (e.g. README_TEMPLATE.md, OPENAPI.md, ADR.md) linked from the body to improve progressive disclosure and token efficiency.

Add an explicit validation/review workflow step (e.g. 'after writing docs, verify examples compile and cross-check against current code to avoid stale comments') with a fix-and-retry loop, since the skill itself warns that outdated comments are worse than none.

Dimension	Reasoning	Score
Conciseness	The body is mostly executable templates and examples with minimal preamble, though large fenced blocks (the full README, OpenAPI schema, ADR templates) pad the token budget with content Claude largely already knows how to structure.	4 / 5
Actionability	It provides concrete, copy-paste-ready templates (JSDoc/TSDoc, OpenAPI/Swagger YAML, README, ADR, component docs) that cover the common cases, with only minor gaps such as 'Implementation' stubs and the 'How to contribute' placeholder.	4 / 5
Workflow Clarity	Sections are clearly organized by documentation type with numbered flows (e.g. the auth component flow) and 'GOOD/BAD' contrast examples, but there is no explicit validate/review checkpoint for catching stale or inconsistent docs despite the skill emphasizing that stale docs are worse than none.	4 / 5
Progressive Disclosure	There is good top-level section structure, but no bundle files exist and all detailed reference material (full README, OpenAPI schema, ADR templates) is inlined in a single SKILL.md rather than split into one-level-deep reference files, so navigation and content splitting could be improved.	3 / 5
	Total	15 / 20 Passed

Description

75%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.

A solid, third-person description that names concrete documentation artifacts and includes an explicit 'Use for' trigger clause. It answers both what and when, but the trigger terms lack synonyms and the coverage is broad rather than comprehensive.

Suggestions

Add natural synonyms and concrete trigger phrases (e.g. 'Use when documenting a codebase, writing a README, adding JSDoc/TSDoc comments, or producing API reference docs') to lift trigger term quality and completeness toward 5.

Sharpen distinctiveness by scoping to the artifact types (e.g. '.md files, JSDoc/TSDoc, OpenAPI/Swagger, ADRs') so it is less likely to overlap with general writing or refactor skills.

Dimension	Reasoning	Score
Specificity	Lists several concrete artifacts ('API docs, README files, inline comments, and technical guides'), naming the domain and multiple specific output types, with only minor gaps in coverage rather than full comprehensiveness.	4 / 5
Completeness	It has a clear 'what' (writing API docs, READMEs, inline comments, technical guides) and an explicit 'when' clause ('Use for documenting codebases, APIs, or writing developer guides'), though the trigger phrasing could be more specific and varied.	4 / 5
Trigger Term Quality	'documenting codebases, APIs, or writing developer guides' covers natural terms users would say, but misses common synonyms like 'docs' or file extensions; good but not comprehensive coverage.	4 / 5
Distinctiveness Conflict Risk	The documentation niche is fairly distinct from generic coding skills, with concrete triggers ('API docs', 'README files', 'developer guides'), though it could overlap slightly with general writing or refactoring skills.	4 / 5
	Total	16 / 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: MoizIbnYousaf/ai-agent-skills
Path: skills/code-documentation/SKILL.md
Commit: 1159592

Reviewed: 18 days 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.