CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

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

80%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.claude/skills/doc-author/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

77%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-structured instructional skill with an explicit workflow, validation checklist, and abundant concrete templates and examples — actionability and workflow clarity are exemplary. It loses points on token efficiency (collaborative/ask/flag-uncertainty principles are restated across multiple sections) and on progressive disclosure, since it is a monolithic single file with no reference bundle despite referencing one in its header comment.

Suggestions

Consolidate the repeated collaborative-mode principles: state them once in 'Operating modes' and have 'Working with humans' and 'Verification guardrails' reference that section instead of restating 'ask before assuming' and 'flag uncertainty'.

Move the Mintlify component conventions and the good/poor examples library into a references/ file (e.g. references/mintlify-conventions.md, references/examples.md) and keep one representative snippet inline per topic, cutting the body substantially.

Remove or resolve the dangling pointers in the header comment — './INSFORGE.md' and 'scripts/update-mintlify-skill.sh' do not exist in this bundle and will dead-end the agent when followed.

DimensionReasoningScore

Conciseness

Mostly efficient instructional content, but collaborative-mode principles are repeated across sections — 'Ask clarifying questions before assuming'/'Ask before assuming' appear in Operating modes, Core principles, and Working with humans, and 'Flag uncertainty' repeats in Core principles, Handling uncertainty, and Verification guardrails. Not 4 because several sections restate the same guidance verbatim in spirit and could be consolidated.

3 / 5

Actionability

Fully concrete, copy-paste-ready guidance: MDX frontmatter template, Mintlify component syntax (<Note>, <Steps>), TODO format ('{/* TODO: Verify the default timeout value ... */}'), exact dialogue examples, good/poor introduction pairs, and a submission checklist. Not 4 because specific examples cover the common cases (drafting, editing, reviewing, structuring) with executable templates throughout.

5 / 5

Workflow Clarity

A clear 6-step workflow (Understand → Research → Plan → Write → Self-review → Submit) with an explicit validation checkpoint: the 8-item self-review checklist run 'Before presenting work (collaborative) or creating a PR (autonomous)', plus mode-specific submit branches. Not 4 because validation is explicit and checklisted, not merely implied.

5 / 5

Progressive Disclosure

No bundle files exist (references/, scripts/, assets/ are all absent), so everything sits inline in a ~440-line SKILL.md; content that clearly belongs in separate files — the Mintlify component conventions and the examples library — is inlined. The header comment also points to './INSFORGE.md' and 'scripts/update-mintlify-skill.sh', which do not exist in this bundle. Not 4 because the split is more than a minor organization gap: substantial reference material is inline with no one-level-deep reference files at all.

3 / 5

Total

16

/

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 states what the skill does and gives an explicit 'Use for...' trigger clause covering both collaborative and autonomous use. It falls just short of exemplary: the when-clause names task modes rather than concrete user moments, and natural trigger synonyms like markdown, MDX, or README are missing.

Suggestions

Rewrite the trigger clause around concrete user moments, e.g. 'Use when the user asks to write, update, or review documentation, or mentions docs, markdown, or MDX pages'.

Add the file formats the body actually targets (markdown/MDX) as trigger terms so the description matches the Mintlify-focused body.

Drop 'Built by Mintlify' from the trigger sentence or move it after the trigger clause — attribution does not help triggering and competes with capability tokens.

DimensionReasoningScore

Specificity

Lists several concrete actions ('Write, edit, and maintain documentation', 'collaborative drafting, autonomous writing, or improving existing docs') but stops short of the comprehensive coverage of the 5 anchor — no file formats or concrete deliverables. Not 3 because more than 1-2 specific actions are named.

4 / 5

Completeness

Both what ('Write, edit, and maintain documentation') and when ('Use for collaborative drafting, autonomous writing, or improving existing docs') are present, but the when-clause names task modes rather than concrete user-moment triggers like 'when the user asks to write or update docs'. Not 3 because an explicit 'Use for...' trigger clause exists.

4 / 5

Trigger Term Quality

Good natural keyword coverage ('documentation', 'docs', 'drafting', 'writing', 'improving existing docs') that users would actually say, but a few common variations are missing (markdown, MDX, README). Not 5 because synonyms and extensions like '.md' or 'MDX' are absent despite the body targeting them.

4 / 5

Distinctiveness Conflict Risk

A mostly distinct niche (documentation authoring, 'Built by Mintlify' adds identity) with only minor overlap risk against general writing/editing skills. Not 5 because 'documentation' is broad enough to collide with README-writing or generic editing skills.

4 / 5

Total

16

/

20

Passed

Validation

93%

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

CriteriaDescriptionResult

referenced_paths_exist

Referenced path issues: 2 missing

Warning

Total

15

/

16

Passed

Repository

InsForge/InsForge

Path

.claude/skills/doc-author/SKILL.md

Reviewed

Table of Contents

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.