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.
94
Quality
92%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Advisory
Suggest reviewing before use
Quality
Discovery
100%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 well-crafted skill description that excels across all dimensions. It clearly specifies the workflow (requirements to AsciiDoc with Vale validation), uses natural trigger terms that users would actually mention, and includes an explicit 'Use when' clause with concrete scenarios. The combination of AsciiDoc, Vale, and specific input sources makes it highly distinctive.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'converts requirements into structured AsciiDoc sections', 'runs Vale for style compliance', and 'produces merge-ready content'. These are clear, actionable capabilities. | 3 / 3 |
Completeness | Clearly answers both what ('converts requirements into structured AsciiDoc sections, runs Vale for style compliance, produces merge-ready content') AND when ('Use when creating or updating AsciiDoc documentation from Jira tickets, GitHub issues, or feature descriptions'). | 3 / 3 |
Trigger Term Quality | Includes natural keywords users would say: 'AsciiDoc', 'documentation', 'Jira tickets', 'GitHub issues', 'feature descriptions', 'Vale', 'merge-ready'. Good coverage of domain-specific terms. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive with specific niche: AsciiDoc format, Vale linting, and specific input sources (Jira, GitHub issues). Unlikely to conflict with generic documentation or other markup skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
85%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-structured orchestrator skill that efficiently describes a multi-phase documentation workflow. Its strengths are excellent workflow clarity with explicit validation loops and good progressive disclosure. The main weakness is that actionability depends heavily on external skill files, making the skill less self-contained for understanding complete execution details.
Suggestions
Consider adding a brief inline example of what the controller.md dispatch logic looks like, so Claude can understand the orchestration pattern without opening external files
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is lean and efficient, avoiding explanations of concepts Claude already knows. Each section serves a clear purpose with no padding or unnecessary context about what AsciiDoc or Vale are. | 3 / 3 |
Actionability | Provides concrete commands (mkdir, vale, gh commands) and clear examples, but relies heavily on external files (skills/controller.md, skills/gather-context.md) for actual execution details. The inline examples are helpful but incomplete without those referenced files. | 2 / 3 |
Workflow Clarity | Excellent multi-step workflow with clear phase sequencing, explicit validation checkpoints (Vale must pass before proceeding), and feedback loops (if validation fails → return to /draft → re-run /validate). Exit criteria are clearly defined for each phase. | 3 / 3 |
Progressive Disclosure | Well-structured overview with clear one-level-deep references to phase skills (skills/{name}.md), controller (skills/controller.md), and guidelines (guidelines.md). Content is appropriately split between quick start, examples, and detailed phase descriptions. | 3 / 3 |
Total | 11 / 12 Passed |
Validation
100%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
- amir-yogev-gh/ai-workflows
- Commit
b213ece
- 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.