docs-writer
Maintains repository documentation accuracy and freshness; use for doc updates, agent or skill changes, staleness checks, changelog entries, and repo explanation requests.
80
76%
Does it follow best practices?
Impact
Pending
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
82%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 solid description that clearly communicates both purpose and trigger conditions in a concise format. Its main strength is the explicit 'use for...' clause with multiple trigger scenarios. Its weakness is moderate specificity—the actions listed are category-level rather than deeply concrete, and there's some overlap risk with general documentation or changelog skills.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (repository documentation) and lists several actions (doc updates, staleness checks, changelog entries, repo explanation requests), but these are somewhat high-level categories rather than deeply concrete actions like 'extract text from tables' or 'fill forms'. | 2 / 3 |
Completeness | Clearly answers both what ('Maintains repository documentation accuracy and freshness') and when ('use for doc updates, agent or skill changes, staleness checks, changelog entries, and repo explanation requests') with explicit trigger scenarios. | 3 / 3 |
Trigger Term Quality | Includes natural keywords users would say: 'doc updates', 'skill changes', 'staleness checks', 'changelog entries', 'repo explanation'. These cover a good range of terms a user might naturally use when requesting documentation maintenance tasks. | 3 / 3 |
Distinctiveness Conflict Risk | While 'repository documentation' is a reasonably specific niche, terms like 'doc updates' and 'repo explanation requests' could overlap with general documentation or README-writing skills. The mention of 'agent or skill changes' adds some distinctiveness but could still conflict with agent/skill management skills. | 2 / 3 |
Total | 10 / 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 documentation maintenance skill with clear workflow sequencing, good progressive disclosure to reference files, and appropriate guardrails. Its main weaknesses are some redundancy (duplicate reference listings) and incomplete actionability for workflows that defer entirely to external files without providing key inline details. The scope boundaries are well-defined, which is valuable for a skill that touches many files.
Suggestions
Consolidate the 'References' section and 'Reference Index' table into a single section to eliminate redundancy.
For Workflows 5, 6, and 7 that defer to `references/extended-workflows.md`, include at least the key concrete steps or output format inline so the skill is actionable without loading the reference.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is mostly efficient but has some redundancy — the References section and Reference Index table convey the same information, and the 'When to Use This Skill' trigger table adds moderate value but could be leaner. The scope tables are useful but slightly verbose with the 'Governed By' column explaining things Claude could infer. | 2 / 3 |
Actionability | Workflows provide clear step-by-step sequences with specific file paths and commands (e.g., `npm run lint:md`), but several workflows defer to external references for full steps (Workflows 5, 6, 7) without providing enough inline detail to be immediately executable. No concrete code examples or exact edit patterns are shown. | 2 / 3 |
Workflow Clarity | Multi-step workflows are clearly sequenced with numbered steps, include validation checkpoints (link verification, lint commands, version checks), and Workflow 3 includes an explicit feedback loop with auto-fix after user confirmation. The guardrails section adds clear constraints for destructive operations. | 3 / 3 |
Progressive Disclosure | Excellent progressive disclosure — the SKILL.md provides a clear overview of all workflows with enough inline detail for common tasks, while appropriately deferring extended workflows and detailed standards to one-level-deep references. The Reference Index table clearly signals when to load each reference. | 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
- jonathan-vella/azure-agentic-infraops
- Commit
ec7b8ff
- 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.