CtrlK
BlogDocsLog inGet started
Tessl Logo

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.

74

Quality

Does it follow best practices?

Impact

No eval scenarios have been run

SecuritybySnyk

Advisory

Suggest reviewing before use

SKILL.md
Quality
Evals
Security

Quality

Content

85%

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

The body is concise, well-structured, and includes an explicit failure/escalation checkpoint, making the workflow clear. It loses points on actionability (real steps live in unreferenced/absent files) and progressive_disclosure (the referenced bundle files are not present to confirm the navigation structure).

Suggestions

Provide the referenced bundle files (commands/*.md, skills/controller.md, guidelines.md) or note they are external so progressive disclosure can be verified against the actual bundle.

Add one concrete, runnable example of a phase invocation (e.g., a sample command and expected artifact path) so the SKILL.md is actionable without fully loading the referenced files.

DimensionReasoningScore

Conciseness

The body is lean (~16 lines of content), assumes Claude's competence, and adds only what is not already known; every line is procedural instruction with no padding or concept explanation.

3 / 3

Actionability

It gives concrete navigation paths (commands/{command}.md, skills/controller.md, .artifacts/${ticket_id}/) but the actual executable steps are deferred to referenced files, so the SKILL.md itself lacks copy-paste-ready commands beyond path pointers.

2 / 3

Workflow Clarity

The Quick Start lays out a clear branching sequence with an explicit failure checkpoint ('If a step fails... stop and report the error... Do not advance') and offers retry/escalation, matching the validation-and-feedback-loop anchor.

3 / 3

Progressive Disclosure

It appropriately points outward (commands, skills/controller.md, guidelines.md) one level deep, but the referenced bundle files do not exist in references/ or scripts/, so the references are signaled yet unverifiable against the actual bundle structure.

2 / 3

Total

10

/

12

Passed

Description

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.

The description is strong: it states concrete capabilities, includes an explicit 'Use when' trigger with natural phrasing, and occupies a clear niche. Voice is appropriately third person and there is no fluff.

DimensionReasoningScore

Specificity

Lists multiple concrete actions: 'converts requirements into structured AsciiDoc sections', 'runs Vale for style compliance', and 'produces merge-ready content', matching the anchor that lists several specific concrete actions.

3 / 3

Completeness

Explicitly answers what it does (convert/validate/produce) and when to use it via the 'Use when creating or updating...' clause, satisfying both halves with explicit triggers.

3 / 3

Trigger Term Quality

Covers natural trigger phrasing users would say ('creating or updating AsciiDoc documentation', 'Jira tickets', 'GitHub issues', 'feature descriptions'), giving good coverage of terms a user would naturally invoke.

3 / 3

Distinctiveness Conflict Risk

The narrow focus on AsciiDoc documentation plus Vale-style compliance and merge-ready output gives it a clear niche unlikely to trigger for unrelated documentation skills.

3 / 3

Total

12

/

12

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.

Validation15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

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