docs-writer
**WORKFLOW SKILL** — Maintains repository documentation accuracy and freshness across the docs site, agent files, and changelog. WHEN: "update docs", "doc gardening", "staleness check", "changelog entry", "repo explanation", "agent change docs", "skill change docs". DO NOT USE FOR: agent definitions (edit `.agent.md` directly), SKILL.md content authoring, site theme/build.
63
73%
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 ./.github/skills/docs-writer/SKILL.mdQuality
Discovery
89%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 strong skill description that excels in completeness and distinctiveness. The explicit WHEN and DO NOT USE FOR clauses make it highly actionable for skill selection. The main weakness is that the core capabilities could be more concretely enumerated—'maintains accuracy and freshness' is somewhat abstract compared to listing specific actions like 'updates stale references' or 'generates changelog entries'.
Suggestions
Replace 'Maintains repository documentation accuracy and freshness' with more concrete actions, e.g., 'Audits docs for staleness, updates cross-references, generates changelog entries, and syncs documentation with code changes'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (repository documentation) and some actions ('maintains accuracy and freshness', 'staleness check', 'changelog entry'), but doesn't list multiple concrete specific actions like 'updates cross-references', 'generates changelog entries', 'audits doc freshness'. The actions are somewhat implied rather than explicitly enumerated. | 2 / 3 |
Completeness | Clearly answers both 'what' (maintains repository documentation accuracy and freshness across docs site, agent files, and changelog) and 'when' (explicit WHEN clause with trigger terms). Also includes a helpful 'DO NOT USE FOR' clause that further clarifies scope and reduces misuse. | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural trigger terms users would say: 'update docs', 'doc gardening', 'staleness check', 'changelog entry', 'repo explanation', 'agent change docs', 'skill change docs'. These are realistic phrases a user would naturally use when needing this skill. | 3 / 3 |
Distinctiveness Conflict Risk | Very distinctive with clear boundaries. The 'DO NOT USE FOR' clause explicitly excludes agent definitions, SKILL.md content authoring, and site theme/build, which sharply delineates this skill from adjacent ones. The trigger terms are specific to documentation maintenance rather than general coding or writing. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
57%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-organized skill that excels at progressive disclosure and clear scoping, with good use of tables for navigation and reference mapping. Its main weakness is that actionability and workflow clarity suffer because all procedural detail is delegated to reference files — the SKILL.md alone doesn't give Claude enough to execute any workflow. There is also notable redundancy between the Scope/Out of Scope section, the Rules section, and the Guardrails section.
Suggestions
Include at least a condensed 3-5 step inline procedure for the most common workflow (e.g., 'Update Existing Documentation') with explicit validation checkpoints, so Claude can act without loading a reference file.
Consolidate the duplicated out-of-scope/guardrails information — the exclusion paths appear in the 'Out of Scope' table, the 'Rules' list, and the 'Guardrails' section. Merge into one authoritative list.
Remove or merge the 'References' bullet list and the 'Reference Index' table — they convey the same information in two formats.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is mostly efficient but has some redundancy — the 'Out of Scope' table and the 'Rules' section repeat the same exclusion paths, and the 'References' section and 'Reference Index' table are largely duplicative. The persona preamble ('You are an expert technical writer...') adds little value. | 2 / 3 |
Actionability | The skill provides concrete validator commands (npm run lint:md, npm run lint:links) and clear file paths, but the actual step-by-step procedures are deferred entirely to references/extended-workflows.md. The SKILL.md itself contains only one-line summaries of each workflow, so Claude cannot execute any workflow from this file alone. | 2 / 3 |
Workflow Clarity | Seven workflows are enumerated with triggers and reference pointers, but no actual steps are shown in the SKILL.md itself — all detail is in extended-workflows.md. There are no explicit validation checkpoints or feedback loops visible here, and since this skill involves editing documentation (a potentially destructive batch operation), the absence of inline verify-then-proceed steps caps this at 2. | 2 / 3 |
Progressive Disclosure | The skill is well-structured as an overview with clear, one-level-deep references to four specific reference files. The workflow table maps each workflow to its reference file, and the Reference Index table tells the agent when to load each file. Navigation is straightforward and well-signaled. | 3 / 3 |
Total | 9 / 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
- jonathan-vella/azure-agentic-infraops
- Commit
05d7617
- 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.