clarity
Establish clarity before starting work. Use when beginning any significant task, when input is vague or stream-of-consciousness, or when requirements seem unclear. Handles messy voice input efficiently. This is the first system in the 5-system framework.
73
51%
Does it follow best practices?
Impact
85%
1.26xAverage score across 6 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./data/1-clarity/SKILL.mdQuality
Discovery
40%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description identifies a reasonable use case (clarifying vague or unclear inputs) but fails to specify what concrete actions the skill performs. The 'what' portion is abstract ('establish clarity'), and the 'when' triggers are overly broad ('any significant task'). The reference to a '5-system framework' is meaningless without additional context and doesn't help Claude select this skill appropriately.
Suggestions
Replace 'establish clarity' with specific concrete actions, e.g., 'Parses vague or stream-of-consciousness input into structured requirements, asks targeted clarifying questions, and produces a clear task summary before work begins.'
Narrow the 'when' clause to avoid the overly broad 'any significant task'—instead specify triggers like 'when user input is ambiguous, rambling, or lacks clear requirements'.
Remove or contextualize the '5-system framework' reference, as it provides no useful selection signal to Claude without further explanation.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description uses vague language like 'establish clarity' and 'beginning any significant task' without listing concrete actions. It doesn't specify what the skill actually does—no mention of asking clarifying questions, parsing requirements, creating structured summaries, or any other tangible action. | 1 / 3 |
Completeness | It has a 'when' clause ('Use when beginning any significant task, when input is vague...'), but the 'what' is extremely weak—'establish clarity' is not a concrete description of what the skill does. The mention of '5-system framework' adds context but not functional clarity. | 2 / 3 |
Trigger Term Quality | It includes some relevant trigger terms like 'vague', 'unclear', 'voice input', and 'requirements', which users might naturally mention. However, it misses common variations like 'ambiguous', 'confusing request', 'what do you mean', or 'clarify'. The phrase 'stream-of-consciousness' is somewhat niche. | 2 / 3 |
Distinctiveness Conflict Risk | The focus on clarification and vague input gives it some distinctiveness, but 'beginning any significant task' is extremely broad and could conflict with many other skills. The '5-system framework' reference adds some specificity but is opaque without context. | 2 / 3 |
Total | 7 / 12 Passed |
Implementation
62%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill has a well-designed tiered approach (messy input vs. full clarity) with a good concrete example for the lightweight path. However, the Full Clarity Protocol section is verbose with questions Claude would naturally ask, and the large output template inflates the token cost. The workflow routing and decision logic are strengths, but actionability suffers in the more formal sections.
Suggestions
Trim the Full Clarity Protocol steps to just the non-obvious questions—Claude already knows to ask 'What are we trying to accomplish?' Focus on project-specific patterns like checking SOURCE_OF_TRUTH.md first.
Move the active-context.md output template to a separate reference file and link to it, keeping only a brief description of what should be documented in the main skill.
Add a concrete example for the Full Clarity Protocol path similar to the Messy Input example, showing a realistic complex task flowing through Steps 1-4 to a filled-out output.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill has some efficient sections (Messy Input Protocol is well-structured) but the Full Clarity Protocol is verbose with questions Claude would naturally know to ask. The output template is lengthy and the 'ask and document' lists under Steps 1-4 are somewhat redundant with Claude's existing reasoning capabilities. | 2 / 3 |
Actionability | The Messy Input Protocol example is concrete and actionable, but the Full Clarity Protocol is more of a checklist of questions to ask rather than executable guidance. The output template is copy-paste ready, but the steps themselves are abstract ('Ask and document: What exactly are we trying to accomplish?'). | 2 / 3 |
Workflow Clarity | The workflow is clearly sequenced with explicit decision points: the Efficiency Rules provide a clear triage (clear → skip, slightly unclear → one-line confirm, very unclear → full extract), the Full Clarity Protocol has numbered steps, and the Transition section provides clear routing to next systems based on conditions. | 3 / 3 |
Progressive Disclosure | The content has good internal structure with the Messy Input Protocol as a quick-start and Full Clarity Protocol for complex work. However, it references external files (active-context.md, SOURCE_OF_TRUTH.md, other systems) without clear links, and the full output template could be in a separate reference file rather than inline. | 2 / 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
- majiayu000/claude-skill-registry-data
- Commit
3dd3ac0
- 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.