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.
88
85%
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 an excellent skill description that clearly articulates specific capabilities, includes natural trigger terms, and explicitly states both what the skill does and when to use it. The combination of AsciiDoc, Vale, and specific input sources (Jira tickets, GitHub issues) creates a highly distinctive and well-scoped description.
| 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 AsciiDoc, runs Vale, produces merge-ready content) and 'when' (explicit 'Use when' clause specifying creating/updating AsciiDoc from Jira tickets, GitHub issues, or feature descriptions). | 3 / 3 |
Trigger Term Quality | Includes strong natural keywords users would say: 'AsciiDoc', 'documentation', 'Vale', 'Jira tickets', 'GitHub issues', 'feature descriptions', 'merge-ready'. These cover multiple natural entry points for this workflow. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive with a clear niche: the combination of AsciiDoc format, Vale linting, and requirement-to-documentation conversion from specific sources (Jira, GitHub issues) makes it very unlikely to conflict with other skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
70%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 orchestration skill with clear phase sequencing, explicit validation loops, and good progressive disclosure to sub-skills. Its main weaknesses are moderate redundancy across sections (phases described three times in slightly different ways) and partial actionability since the real execution details live in referenced sub-skills. The feedback loop for /validate is well-defined and the user approval gate at /plan is a good safety checkpoint.
Suggestions
Consolidate the Phases and Phase Transitions sections into a single section to eliminate redundancy and save tokens.
Add a concrete example of what 01-context.md output looks like (even a brief skeleton) so Claude knows the expected artifact format without opening sub-skills.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Generally efficient but has some redundancy — the phase list appears in multiple forms (Phases section, Phase Transitions section, and Example Session), and some explanatory text like 'Systematic documentation creation through these phases' adds little value. The content could be tightened by consolidating the phases and transitions into one section. | 2 / 3 |
Actionability | Provides concrete commands (vale, gh issue view, mkdir) and specific file paths, but most of the actual work is delegated to sub-skills (skills/gather-context.md, skills/controller.md) without showing their content. The examples are helpful but incomplete — e.g., the /gather example shows steps but doesn't provide executable code for 'Synthesize Why, What, and technical changes.' | 2 / 3 |
Workflow Clarity | The multi-phase workflow is clearly sequenced with explicit exit criteria for each phase, a mandatory user approval gate before /draft, and a well-defined feedback loop (validate → fix → re-validate). The Phase Transitions section explicitly states when to proceed and when to loop back, which is exactly what's needed for this kind of orchestration skill. | 3 / 3 |
Progressive Disclosure | The skill serves as a clear orchestration overview, pointing to one-level-deep references (skills/controller.md, skills/{name}.md, guidelines.md) without nesting. Content is appropriately split between this overview and the referenced phase skills, with the artifact directory structure clearly explained inline. | 3 / 3 |
Total | 10 / 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
81213f2
- 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.