Write clear and helpful user guides and tutorials for end users. Use when creating onboarding docs, how-to guides, or FAQ pages. Handles user-focused documentation, screenshots, step-by-step instructions.
85
78%
Does it follow best practices?
Impact
97%
1.15xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./.agent-skills/user-guide-writing/SKILL.mdQuality
Discovery
92%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 specific capabilities and includes explicit 'Use when' guidance with natural trigger terms. The description uses proper third-person voice and covers multiple concrete deliverables. The only minor weakness is potential overlap with other documentation-related skills, though the 'end user' focus helps differentiate it.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'user guides and tutorials', 'onboarding docs', 'how-to guides', 'FAQ pages', 'screenshots', 'step-by-step instructions'. These are concrete, actionable deliverables. | 3 / 3 |
Completeness | Clearly answers both what ('Write clear and helpful user guides and tutorials', 'Handles user-focused documentation, screenshots, step-by-step instructions') AND when ('Use when creating onboarding docs, how-to guides, or FAQ pages') with explicit trigger guidance. | 3 / 3 |
Trigger Term Quality | Includes natural keywords users would say: 'user guides', 'tutorials', 'onboarding docs', 'how-to guides', 'FAQ pages', 'screenshots', 'step-by-step instructions'. These cover common variations of user documentation requests. | 3 / 3 |
Distinctiveness Conflict Risk | While it specifies 'user-focused' and 'end users', it could potentially overlap with general documentation skills or technical writing skills. The 'user guides' and 'tutorials' focus helps distinguish it, but 'documentation' is still somewhat broad. | 2 / 3 |
Total | 11 / 12 Passed |
Implementation
64%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill provides excellent concrete templates for user documentation but suffers from verbosity and structural issues. The templates are actionable and copy-paste ready, but the skill would benefit from being more concise about principles rather than providing full example documents inline. The 'Step 1-4' framing is misleading since these are independent document types, not a sequential process.
Suggestions
Replace full inline templates with concise structural patterns and link to separate template files (e.g., templates/quick-start.md, templates/how-to.md)
Add a validation checklist for reviewing documentation quality before publishing (readability score, screenshot verification, link checking)
Remove empty placeholder sections (Example 1, Example 2) and redundant metadata that adds no instructional value
Reframe 'Steps 1-4' as 'Document Types' since they are independent templates, not a sequential workflow
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill provides extensive template examples which are useful but verbose. The examples are largely copy-paste templates rather than teaching principles Claude could apply. Some sections like metadata and empty example placeholders add no value. | 2 / 3 |
Actionability | The skill provides fully concrete, copy-paste ready markdown templates for each documentation type (quick start, how-to, FAQ, tutorial). The examples are complete and executable with clear structure and formatting. | 3 / 3 |
Workflow Clarity | The skill presents four document types as 'steps' but they're actually independent templates, not a sequential workflow. There's no validation checkpoint for reviewing documentation quality or user testing before publishing. | 2 / 3 |
Progressive Disclosure | The skill is a monolithic file with all templates inline. The output format section suggests a file structure but the actual content could benefit from splitting templates into separate reference files, keeping SKILL.md as an overview. | 2 / 3 |
Total | 9 / 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_version | 'metadata.version' is missing | Warning |
Total | 10 / 11 Passed | |
c033769
Table of Contents
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.