Tessl • The management layer for AI agent skills

SkillPublic

document

Generate, format, and validate code documentation — docstrings, JSDoc, OpenAPI/Swagger specs, documentation sites, and developer guides.

Quality

79%

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

Quality

Content

86%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 lean, highly actionable skill body: four well-structured modes with concrete commands, named tools, and validation checkpoints in the modes that need them. The one real defect is that the repeatedly referenced references/documentation.md is missing from the bundle, making the skill's otherwise-excellent progressive disclosure a dead end.

Suggestions

Create references/documentation.md with the referenced sections (Python Docstrings, TypeScript JSDoc, OpenAPI 3.1, FastAPI, NestJS, Documentation Sites, Getting Started Guide Structure), or remove the four "Reference:" lines until the file exists.

Add validation steps to the site and guide modes (e.g. "mkdocs build --strict" for the site; run every guide command to confirm expected output) to match the checkpoint quality of the docstrings and openapi modes.

Add an explicit error-recovery loop after validation commands (e.g. "If lint fails: fix schema issues and re-run until clean") to reach full workflow clarity.

Dimension	Reasoning	Score
Conciseness	The body is pure procedural instruction — numbered steps, rules, and exact commands — with zero explanation of concepts Claude already knows and no padding; every token earns its place. Each mode is a lean, self-contained checklist.	5 / 5
Actionability	Fully executable, copy-paste-ready commands with exact flags ("python -m doctest file.py", "npx @redocly/cli lint openapi.yaml", "interrogate --fail-under=80 src/"), named tools and themes, and specific decorators (@ApiProperty, @ApiOperation, @ApiResponse) covering the common cases in every mode. No pseudocode anywhere.	5 / 5
Workflow Clarity	Each mode has a clear numbered sequence, and validation checkpoints appear where they matter (docstring steps 4-5 verify examples and coverage; openapi step 7 lints the spec). It is not 5 because the site and guide modes lack validation steps and no mode includes an explicit fix-and-retry feedback loop.	4 / 5
Progressive Disclosure	Sections are well organized and every mode ends with a clearly signaled one-level-deep pointer ("Reference: references/documentation.md → ..."). However, that referenced file does not exist in the bundle — all four pointers are dead ends — which is a navigation failure beyond the "minor organization gaps" of the 4 anchor, and comparable in effect to a broken reference chain.	3 / 5
	Total	17 / 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.

A specific, third-person description that clearly states what the skill does across a well-enumerated set of documentation artifacts, with good natural trigger terms. Its main weakness is the complete absence of any "Use when..." trigger clause, which caps completeness and slightly weakens trigger coverage.

Suggestions

Append an explicit trigger clause, e.g. "Use when asked to write or improve docstrings, document a REST API, generate an OpenAPI spec, or set up a documentation site."

Include natural phrasing variations users actually say — "document my code", "API docs", "write documentation" — alongside the current artifact names.

Dimension	Reasoning	Score
Specificity	Concrete verbs ("Generate, format, and validate") are applied to a well-enumerated artifact list ("docstrings, JSDoc, OpenAPI/Swagger specs, documentation sites, and developer guides"), giving several specific actions. It falls short of 5 because "format" is generic and the action set is less comprehensive than the top anchor.	4 / 5
Completeness	The "what" is clear (generate/format/validate code documentation across named artifact types), but there is no "Use when..." clause or equivalent explicit trigger guidance anywhere in the description, which the judging guidelines cap at 3. It is not 4 because the "when" is entirely absent rather than merely imprecise.	3 / 5
Trigger Term Quality	Natural domain terms users would say ("docstrings", "JSDoc", "OpenAPI/Swagger specs", "documentation sites", "developer guides") are present with good coverage. It is not 5 because common variations like "document my code", "API docs", or "docs" are missing; it is clearly above 3's partial keyword coverage.	4 / 5
Distinctiveness Conflict Risk	The enumerated artifacts (docstrings, JSDoc, OpenAPI/Swagger) carve out a clear code-documentation niche with distinct triggers. Minor overlap risk remains with generic document-handling skills (e.g., "documents" vs "documentation" confusion), keeping it below 5.	4 / 5
	Total	15 / 20 Passed

Validation

87%

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

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning
referenced_paths_exist	Referenced path issues: 4 missing	Warning

	Total	14 / 16 Passed

Repository: nitinjain999/platform-skills
Path: skills/document/SKILL.md
Revision: c2e75b7

Reviewed: 17 hours ago

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.

document

Table of Contents

Is this your skill?