docs-workflow
Four slash commands for documentation lifecycle: /docs, /docs-init, /docs-update, /docs-claude. Create, maintain, and audit CLAUDE.md, README.md, and docs/ structure with smart templates. Use when: starting new projects, maintaining documentation, auditing docs for staleness, or ensuring CLAUDE.md matches project state.
Overall
score
77%
Does it follow best practices?
If you maintain this skill, you can automatically optimize it using the tessl CLI to improve its score:
npx tessl skill review --optimize ./path/to/skillValidation for skill structure
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 a strong skill description that clearly articulates what the skill does (four slash commands for documentation lifecycle management) and when to use it (explicit 'Use when:' clause with multiple scenarios). The description uses third person voice, includes specific file targets and command names as natural trigger terms, and carves out a distinct niche that minimizes conflict risk with other skills.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'Create, maintain, and audit CLAUDE.md, README.md, and docs/ structure with smart templates' and names four specific slash commands (/docs, /docs-init, /docs-update, /docs-claude). | 3 / 3 |
Completeness | Clearly answers both what (four slash commands for documentation lifecycle, create/maintain/audit specific files) AND when (explicit 'Use when:' clause covering starting projects, maintaining docs, auditing staleness, ensuring CLAUDE.md matches project state). | 3 / 3 |
Trigger Term Quality | Includes natural keywords users would say: 'documentation', 'CLAUDE.md', 'README.md', 'docs/', 'new projects', 'maintaining documentation', 'auditing docs', 'staleness'. The slash command names also serve as explicit triggers. | 3 / 3 |
Distinctiveness Conflict Risk | Clear niche focused specifically on documentation lifecycle with distinct file targets (CLAUDE.md, README.md, docs/) and specific slash commands. Unlikely to conflict with general coding or other documentation skills due to the specific scope. | 3 / 3 |
Total | 12 / 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 skill provides good organizational structure and clear command documentation, but lacks the concrete, executable guidance that would make it highly actionable. It describes what commands do rather than showing exactly how they work or what output to expect. The workflow sections would benefit from explicit validation steps and error handling guidance.
Suggestions
Add concrete examples of command output or show what a generated CLAUDE.md looks like after running /docs-init
Include validation steps after each command (e.g., 'Verify CLAUDE.md was created with: ls -la CLAUDE.md')
Remove explanatory content about what CLAUDE.md and README.md contain - Claude knows these concepts; focus on project-specific template differences instead
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is reasonably efficient but includes some unnecessary explanation (e.g., explaining what CLAUDE.md contains, listing obvious README sections). Tables and structure add clarity but some sections could be tightened. | 2 / 3 |
Actionability | Commands are clearly listed and quick start shows usage, but lacks executable code examples. The skill describes what commands do rather than showing concrete output or implementation details Claude would need. | 2 / 3 |
Workflow Clarity | Multi-step processes are listed (e.g., what /docs-init does) but lack explicit validation checkpoints. The 'When to Run Each Command' table helps, but there's no error recovery guidance or verification steps after running commands. | 2 / 3 |
Progressive Disclosure | Well-organized with clear sections, tables for quick reference, and appropriate references to templates directory. Content is logically structured from overview to details without excessive nesting. | 3 / 3 |
Total | 9 / 12 Passed |
Validation
75%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 12 / 16 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
metadata_version | 'metadata' field is not a dictionary | Warning |
license_field | 'license' field is missing | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
body_output_format | No obvious output/return/format terms detected; consider specifying expected outputs | Warning |
Total | 12 / 16 Passed | |
- 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.