create-documentation

Generate markdown documentation for a module or feature

Quality

57%

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 ./.opencode/skills/create-documentation/SKILL.md

Quality

Content

65%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is highly actionable with concrete paths, templates, and a placement table, and it cleanly defers style guidance to an external reference. Its weaknesses are redundant workflow sections, a lack of validation checkpoints, and an oversized inline template that belongs in a reference file.

Suggestions

Consolidate 'Your Task', 'Process', and 'Begin' into a single sequenced workflow to remove redundancy and tighten conciseness.

Add validation checkpoints such as verifying MDX renders, confirming cross-reference links resolve, and checking meta.json navigation order before finishing.

Move the full MDX template and file-tree into a reference file (e.g. references/MDX_TEMPLATE.mdx) and link to it, reducing SKILL.md length and improving progressive disclosure.

Dimension	Reasoning	Score
Conciseness	The body avoids explaining basic concepts and is mostly efficient, but 'Your Task', 'Process', and 'Begin' overlap heavily and 'Guidelines' re-summarizes WRITING_STYLE.md after the intro already points to it, so it could be tightened; not a 1 because there is no concept-padding.	2 / 3
Actionability	Concrete file paths (content/docs/api/<class>.mdx), a 'where to put docs' table, a full MDX template, and a meta.json example give copy-paste-ready guidance; the template placeholders are intentional scaffolding rather than pseudocode.	3 / 3
Workflow Clarity	Steps are clearly sequenced, but there are no validation/verification checkpoints (e.g., confirm MDX renders, links resolve, meta.json order is correct) and the duplicated step lists dilute clarity, fitting 'steps listed but validation gaps.'	2 / 3
Progressive Disclosure	The WRITING_STYLE.md reference is clearly signaled and one level deep, but the skill is ~160 lines with the full MDX template and file tree inline and no bundle files to split into, so content that could be separate remains inline; not a 3 because it exceeds the 'under 50 lines' simple-skill allowance.	2 / 3
	Total	9 / 12 Passed

Description

50%

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 states a clear single action and domain but omits explicit trigger guidance and lists only one action, leaving all dimensions at the mid level. Adding a 'Use when...' clause and enumerating concrete documentation types would lift specificity, completeness, and distinctiveness together.

Suggestions

Add an explicit trigger clause, e.g. 'Use when the user asks to create or update docs, API references, feature guides, or MDX pages for a module or feature.'

Enumerate concrete actions instead of one, e.g. 'Generate or update API reference pages, feature guides, and conceptual docs as MDX files.'

Include natural trigger terms users actually say (docs, documentation, API docs, .mdx) to improve trigger-term coverage and distinctiveness.

Dimension	Reasoning	Score
Specificity	"Generate markdown documentation for a module or feature" names a single concrete action and its domain, matching the 'names domain and some actions, but not comprehensive' anchor rather than the multiple-actions bar for a 3.	2 / 3
Completeness	It answers 'what' but provides no 'Use when...' clause or equivalent explicit trigger guidance, which per the judging guidelines caps completeness at 2; it is not a 1 because the 'what' is clearly stated.	2 / 3
Trigger Term Quality	"markdown documentation" is a natural term a user might say, but common variations (docs, API docs, .mdx, documentation) are absent, fitting 'some relevant keywords but missing common variations.'	2 / 3
Distinctiveness Conflict Risk	"markdown documentation" narrows the niche somewhat, but "module or feature" is broad and could overlap with general doc or code-comment skills, fitting 'somewhat specific but could still overlap.'	2 / 3
	Total	8 / 12 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 suspicious	Warning

	Total	15 / 16 Passed

Repository: LibPDF-js/core
Path: .opencode/skills/create-documentation/SKILL.md
Commit: 36bf165

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