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.
Install with Tessl CLI
npx tessl i github:supercent-io/skills-template --skill user-guide-writing85
Quality
78%
Does it follow best practices?
Impact
97%
1.15xAverage score across 3 eval scenarios
Optimize this skill with Tessl
npx tessl skill review --optimize ./.agent-skills/user-guide-writing/SKILL.mdDiscovery
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 main weakness is potential overlap with other documentation-related skills, which could be addressed by more explicitly distinguishing it from technical/developer documentation.
| 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 distinction from developer documentation or API docs is implied but not explicitly stated. | 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 functions more as a template library than a teaching skill. It's actionable but verbose, including full example documents that could be referenced externally. The skill would benefit from focusing on principles and decision-making guidance rather than embedding complete templates inline.
Suggestions
Extract the full template examples into separate reference files (e.g., templates/quick-start.md, templates/how-to.md) and keep SKILL.md focused on when to use each type and key principles
Add a decision tree or guidance for choosing between documentation types (quick start vs tutorial vs how-to) based on user needs
Remove empty placeholder sections (Example 1, Example 2) and unnecessary metadata that doesn't aid Claude's task execution
Add validation steps such as 'Test instructions with a new user' or 'Verify all links and screenshots are current' to ensure documentation quality
| 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 sequential steps but doesn't explain when to use each or how they relate. There's no validation checkpoint for reviewing documentation quality or user testing. The workflow is more of a template catalog than a guided process. | 2 / 3 |
Progressive Disclosure | The skill is a monolithic document with all templates inline. The output format section hints at file organization but the actual content could benefit from splitting templates into separate reference files, keeping SKILL.md as an overview with principles and links. | 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 | |
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.