docs-writing-style
Two-mode writing guide — exports a paste-ready style prompt for coding agents (handoff mode) or reviews a draft against the documentation quality rubric (review mode).
58
67%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/documentation/docs-writing-style/SKILL.mdQuality
Discovery
57%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 communicates a clear and distinctive two-mode concept but lacks explicit trigger guidance ('Use when...') and natural user-facing keywords. The specificity of actions is moderate — the modes are named but the concrete outputs and evaluation criteria could be described more precisely.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user asks for help with documentation style, writing guidelines for code agents, or wants a draft reviewed for documentation quality.'
Include more natural trigger terms users might say, such as 'writing style', 'docs review', 'documentation standards', 'style guide', 'writing quality check'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (writing/documentation) and two specific modes (handoff mode and review mode) with brief descriptions of each, but the actions are somewhat abstract — 'exports a paste-ready style prompt' and 'reviews a draft against the documentation quality rubric' could be more concrete about what specific outputs or evaluations are produced. | 2 / 3 |
Completeness | The 'what' is reasonably covered with the two modes described, but there is no explicit 'Use when...' clause or equivalent trigger guidance telling Claude when to select this skill. The when is only implied by the mode descriptions. | 2 / 3 |
Trigger Term Quality | Includes some relevant terms like 'style prompt', 'coding agents', 'review', 'draft', 'documentation quality rubric', but misses many natural user phrases like 'writing style', 'docs review', 'documentation standards', 'style guide', or 'writing guidelines'. A user might not naturally say 'handoff mode' or 'paste-ready style prompt'. | 2 / 3 |
Distinctiveness Conflict Risk | The two-mode structure (handoff mode for coding agents, review mode against a documentation quality rubric) is quite distinctive and unlikely to conflict with other skills. The specific niche of generating style prompts for coding agents and reviewing documentation quality is narrow and well-defined. | 3 / 3 |
Total | 9 / 12 Passed |
Implementation
77%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, dual-mode skill with strong actionability and clear workflows. The key rules section provides excellent concrete guidance with specific do/don't examples. The main weaknesses are moderate verbosity in peripheral sections (core principle philosophy, feedback/adaptation sections) and a large inline rules block that partially duplicates what should be in the referenced style-principles.md file.
Suggestions
Consider moving the 'Did this help?' and 'Adapt to your docs site' sections into a separate CONTRIBUTING.md or README, as they are operational concerns rather than skill instructions.
Clarify the relationship between the inline 'Key rules' section and the referenced 'references/style-principles.md' — if they overlap, keep only a brief summary inline and point to the reference file for the full list.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is mostly efficient and well-structured, but includes some unnecessary content like the 'Core principle' philosophical section, the 'Did this help?' section with issue-filing instructions, and the 'Adapt to your docs site' section which adds operational overhead that could be in a separate file. The key rules section is dense but justified as a quick reference. | 2 / 3 |
Actionability | The skill provides highly concrete, actionable guidance: exact output format for review mode (PASS/FAIL/WARN template), specific rules with examples of correct vs incorrect patterns (e.g., 'No "Configure Your Auth Provider" — use "Configure your auth provider"'), exact SDK variable names, and clear step-by-step procedures for both modes. | 3 / 3 |
Workflow Clarity | Both modes have clearly sequenced workflows. Handoff mode has 3 explicit steps with an optional tailoring step. Review mode has 5 steps with a specific output format, priority grouping, and a clear closing action. The mode selection table at the top provides unambiguous routing. The review mode includes implicit validation (rubric-based checking) with structured output. | 3 / 3 |
Progressive Disclosure | The skill references external files well (references/style-principles.md, references/llms-judge-rubric.md, references/scalekit-style-prompt-block.md, references/_template-style-prompt-block.md) with clear one-level-deep navigation. However, no bundle files were provided to verify these references exist, and the 'Key rules' section is a substantial inline block (~40 lines) that could arguably be in a separate reference file, especially since style-principles.md is already referenced. | 2 / 3 |
Total | 10 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
metadata_field | 'metadata' should map string keys to string values | Warning |
Total | 10 / 11 Passed | |
- Repository
- saif-shines/devex-kit
- Commit
b683754
- 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.