docs-writer

Documentation workflow that converts requirements into structured AsciiDoc sections, runs Vale for style compliance, and produces merge-ready content. Use when creating or updating AsciiDoc documentation from Jira tickets, GitHub issues, or feature descriptions.

Quality

83%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

The canonical home for this skill is docs-writer in flightctl/ai-workflows

Quality

Content

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

An exemplary orchestrator body: lean routing logic, explicit error handling with an escalation path, and purpose-labeled pointers to detail files. The only deductions are minor — phase semantics and checkpoints live in external files, and those referenced files are absent from the bundle being evaluated.

Dimension	Reasoning	Score
Conciseness	Every line is a routing decision or failure rule with zero padding; the body assumes Claude's competence and adds nothing it already knows, matching the lean anchor 5.	5 / 5
Actionability	Concrete executable guidance (read `commands/{command}.md`, check `.artifacts/${ticket_id}/`, read `skills/controller.md`) with clear branching, but "execute the `/gather` phase" defers its meaning entirely to an external file — a minor gap.	4 / 5
Workflow Clarity	The dispatch sequence is clearly numbered and includes an explicit failure checkpoint with retry/escalate feedback ("stop and report the error... Offer to retry... or escalate"), but success checkpoints for the phases themselves are deferred elsewhere, leaving minor validation gaps.	4 / 5
Progressive Disclosure	A clean overview with well-signaled, one-level-deep references, each with its purpose stated ("For principles, hard limits, safety, quality, and escalation rules, see `guidelines.md`"). However, none of the referenced files (`commands/`, `skills/controller.md`, `guidelines.md`) exist in the provided bundle, so navigation cannot be fully verified.	4 / 5
	Total	17 / 20 Passed

Description

83%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 strong description: third-person voice, concrete named tools, and an explicit "Use when" clause with distinct trigger sources. The main gaps are missing common trigger variations (notably the .adoc file extension) and a slightly vague "merge-ready content" claim.

Suggestions

Add the .adoc file extension and common synonyms (e.g., "adoc files", "docs") to the trigger clause to improve natural-term coverage.

Clarify what "produces merge-ready content" means concretely (e.g., opens a pull request or passes CI checks) to remove the last vague claim.

Dimension	Reasoning	Score
Specificity	Names three concrete actions with specific tools ("converts requirements into structured AsciiDoc sections", "runs Vale for style compliance", "produces merge-ready content"), but "merge-ready content" is slightly underspecified, matching anchor 4 rather than comprehensive anchor 5.	4 / 5
Completeness	Explicitly answers both what (three concrete actions) and when ("Use when creating or updating AsciiDoc documentation from Jira tickets, GitHub issues, or feature descriptions") with concrete trigger phrases, matching anchor 5.	5 / 5
Trigger Term Quality	Good natural keyword coverage ("AsciiDoc documentation", "Jira tickets", "GitHub issues", "feature descriptions", "creating or updating") but misses common variations like ".adoc", "adoc", "docs", or "technical writing".	4 / 5
Distinctiveness Conflict Risk	The AsciiDoc/Vale/Jira niche is mostly distinct with clear trigger sources, but the generic "Documentation workflow" opening leaves minor overlap risk with other documentation-writing skills, fitting anchor 4 better than 5.	4 / 5
	Total	17 / 20 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
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: amir-yogev-gh/ai-workflows
Path: docs-writer/SKILL.md
Commit: 2bd6607

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.