doc-author

Write, edit, and maintain documentation. Use for collaborative drafting, autonomous writing, or improving existing docs. Defaults to collaborative mode where the human makes final decisions. Built by Mintlify.

Quality

65%

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 ./.claude/skills/doc-author/SKILL.md

Quality

Content

62%

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

The skill provides a clear, well-sequenced workflow with a self-review checklist and concrete MDX examples, but it is a long monolithic document that re-teaches conventions Claude already knows and keeps reference-worthy detail inline rather than split into bundle files.

Suggestions

Move the Mintlify conventions (file format, components, internal links) and the Examples section into a references file (e.g., references/mintlify-conventions.md) and link to them from the body to improve progressive disclosure.

Cut the explanations of Claude-known style rules (active voice, sentence case, avoiding filler conjunctions, no emoji) down to brief reminders, trusting Claude's competence.

Tighten the many illustrative quote blocks in "Working with humans" to one or two representative examples to reduce padding.

Dimension	Reasoning	Score
Conciseness	The body explains conventions Claude already knows (active voice, sentence case, avoiding "moreover"/"furthermore", no emoji) and pads them with many illustrative quote blocks; it is useful and organized but could be tightened considerably, so it sits below the lean 3-anchor.	2 / 3
Actionability	Concrete MDX frontmatter, component (<Note>, <Steps>), link-path, and TODO-format examples are copy-paste ready, but a large portion is abstract collaborative-process guidance ("Draft content for the human to refine", "Suggest improvements with clear reasoning"), so it does not fully reach the 3-anchor.	2 / 3
Workflow Clarity	A numbered Workflow (Understand → Research → Plan → Write → Self-review → Submit) is clearly sequenced, and the self-review checklist acts as an explicit validation checkpoint before presenting or opening a PR, matching the 3-anchor.	3 / 3
Progressive Disclosure	No bundle files exist and the ~440-line body is monolithic; content that could be split out (Mintlify conventions, the examples section, common tasks) is inline with no external references, matching the 2-anchor of content that should be separate kept inline.	2 / 3
	Total	9 / 12 Passed

Description

67%

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 cleanly answers both what and when with an explicit trigger clause, but the domain is broad and the trigger terms lean on the skill's own mode vocabulary rather than language users naturally say.

Suggestions

Swap mode-framed triggers ("collaborative drafting", "autonomous writing") for natural user phrasing such as "write docs", "edit documentation", "draft technical writing", or "improve existing docs".

Add concrete documentation actions (e.g., "add MDX pages", "write API references", "fix style inconsistencies") to lift specificity beyond general verbs.

Tighten the niche with a distinguishing clause (e.g., "for Mintlify-powered MDX documentation sites") to reduce overlap with generic writing skills.

Dimension	Reasoning	Score
Specificity	Names the documentation domain and several actions ("Write, edit, and maintain documentation", "drafting", "improving existing docs"), but these are general verbs rather than the concrete operations (e.g., "extract text", "fill forms", "merge") that define the 3-anchor.	2 / 3
Completeness	An explicit "Use for..." trigger clause follows a clear statement of what the skill does ("Write, edit, and maintain documentation"), answering both what and when without inference.	3 / 3
Trigger Term Quality	The "Use for collaborative drafting, autonomous writing, or improving existing docs" clause offers some relevant keywords, but "collaborative drafting"/"autonomous writing" reflect the skill's internal framing more than natural user phrasing, and common variations like "docs" or "technical writing" are absent.	2 / 3
Distinctiveness Conflict Risk	"documentation" is a broad domain that could overlap with general writing or code-comment skills; the mode/PR-based review framing narrows the niche but does not make it clearly distinct.	2 / 3
	Total	9 / 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
referenced_paths_exist	Referenced path issues: 2 missing	Warning

	Total	15 / 16 Passed

Repository: InsForge/InsForge
Path: .claude/skills/doc-author/SKILL.md
Commit: 9cf009b

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