writing-docs

Use when writing, restructuring, or reviewing any prose documentation — a tutorial, how-to guide, reference page, or explanation/conceptual doc — for a public docs site (e.g. Mintlify MDX, docs/, README material), a getting-started guide, an API/CLI reference page, or a "why we built it this way" conceptual page. Applies the Diátaxis framework (see https://diataxis.fr/) — every document belongs to exactly one of the four quadrants (tutorial / how-to guide / reference / explanation), and mixing quadrants inside one document is the single most common documentation failure. Covers the four-quadrant compass for picking the right form, per-quadrant structure templates, an anti-pattern list for quadrant drift, and generic voice/craft rules — repo-specific voice and target output format (e.g. Mintlify MDX) are resolved from the repo's docs-manifest (falling back to project-context), never hardcoded here.

Quality

71%

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 ./plugins/sdlc/skills/writing-docs/SKILL.md

Quality

Content

56%Scale 1-5

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

This skill demonstrates strong domain knowledge and provides genuinely useful structure templates and a practical self-review checklist, but it is undermined by significant verbosity — much of the content explains documentation theory that Claude already understands, rather than focusing on the novel, actionable parts (templates, compass decision tool, anti-pattern detection, voice resolution hierarchy). The monolithic structure makes it harder to scan and consumes more context window than necessary.

Suggestions

Cut the 'Why Diátaxis' section and the cooking analogy entirely — Claude understands documentation theory; replace with a 2-line summary linking to diataxis.fr for background.

Trim the four quadrant descriptions (Tutorial, How-to guide, Reference, Explanation) to 1-2 sentences each — the templates already encode the structural rules, so the prose descriptions are largely redundant.

Split the four per-quadrant structure templates into a separate referenced file (e.g., `quadrant-templates.md`) to reduce the main skill's length and improve progressive disclosure.

Add a concrete before/after example showing quadrant drift being fixed — e.g., a how-to guide paragraph with inline theory, then the corrected version with the theory linked out.

Dimension	Reasoning	Score
Conciseness	The skill is significantly verbose. It extensively explains the Diátaxis framework — what tutorials are, what how-to guides are, what reference is, what explanation is — all concepts Claude already knows well. The 'Why Diátaxis' section spends ~200 words arguing for something that could be stated in one sentence. The cooking analogy at the end is unnecessary padding. The anti-patterns table, while useful, restates the same principle ('quadrant drift') four times with lengthy explanations. Much of this content explains documentation theory rather than providing actionable, novel instructions.	2 / 5
Actionability	The skill provides concrete, usable structure templates for all four quadrants with actual markdown scaffolds including frontmatter. The self-review checklist is actionable. The compass decision table is a practical tool. However, the templates contain TODO placeholders rather than filled examples showing what good output looks like for each quadrant, and there are no before/after examples of fixing quadrant drift — the anti-patterns describe problems but don't show concrete rewrites.	4 / 5
Workflow Clarity	The workflow is reasonably clear: identify quadrant via compass → use template → resolve voice/format from manifest hierarchy → run self-review checklist. The checklist at the end serves as a validation step. However, the overall sequencing is implicit rather than explicitly numbered — the reader must piece together the workflow from scattered sections (When to Use, The Compass, templates, Voice resolution, Self-Review). A single explicit workflow sequence would improve clarity.	4 / 5
Progressive Disclosure	The skill is a monolithic ~400-line document with no bundle files to offload content to. The four quadrant templates alone consume a large portion of the file and could be split into separate referenced files. The anti-patterns table, the compass explanation, and the voice/craft rules all compete for attention in a single long document. References to external sources (diataxis.fr, docs-manifest.md, project-context.md) are present but the skill itself would benefit from splitting its own content across files.	3 / 5
	Total	13 / 20 Passed

Description

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

This is a strong, well-crafted description that clearly communicates both what the skill does and when to use it. It opens with an explicit 'Use when...' clause packed with natural trigger terms and document types, then explains the Diátaxis methodology and what the skill covers. The description is distinctive and unlikely to be confused with generic writing or code documentation skills, though it could benefit from a few additional common user phrasings.

Dimension	Reasoning	Score
Specificity	Lists several concrete actions: writing, restructuring, reviewing prose documentation; picking the right quadrant form; per-quadrant structure templates; anti-pattern detection for quadrant drift; voice/craft rules. Minor gaps in that some actions are described at a meta level (e.g., 'covers the four-quadrant compass') rather than as direct verbs.	4 / 5
Completeness	Explicitly answers both 'what' (applies Diátaxis framework, covers four-quadrant compass, structure templates, anti-pattern list, voice/craft rules) and 'when' (opens with 'Use when writing, restructuring, or reviewing any prose documentation' followed by concrete trigger scenarios like tutorials, how-to guides, reference pages, conceptual docs, public docs sites).	5 / 5
Trigger Term Quality	Includes strong natural trigger terms: 'tutorial', 'how-to guide', 'reference page', 'explanation', 'docs site', 'README', 'getting-started guide', 'API/CLI reference', 'Mintlify MDX', 'Diátaxis'. Missing some common user phrases like 'write docs', 'documentation review', 'technical writing', or file extensions like '.md'/'.mdx'.	4 / 5
Distinctiveness Conflict Risk	Highly distinctive due to the specific Diátaxis framework focus, the four-quadrant taxonomy, and the explicit scope of prose documentation for public docs sites. The mention of quadrant drift anti-patterns and the distinction from repo-specific voice/format further carve out a clear niche unlikely to conflict with general writing or code documentation skills.	5 / 5
	Total	18 / 20 Passed

Validation

100%

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 — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository: whimzyLive/nightshift-ai
Path: plugins/sdlc/skills/writing-docs/SKILL.md
Commit: 7741177

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