requirements-clarity
Clarify ambiguous requirements through focused dialogue before implementation. Use when requirements are unclear, features are complex (>2 days), or involve cross-team coordination. Ask two core questions - Why? (YAGNI check) and Simpler? (KISS check) - to ensure clarity before coding.
Install with Tessl CLI
npx tessl i github:softaworks/agent-toolkit --skill requirements-clarity70
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/skillAgent success when using this skill
Validation for skill structure
Discovery
85%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 well-structured skill description that clearly articulates both purpose and trigger conditions. The explicit 'Use when...' clause with concrete criteria (>2 days complexity, cross-team coordination) is strong. The main weakness is reliance on technical acronyms (YAGNI, KISS) that users may not naturally use when requesting help.
Suggestions
Add more natural trigger terms users might say, such as 'scope', 'spec', 'planning phase', 'design review', or 'before I start coding'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists specific concrete actions: 'Clarify ambiguous requirements through focused dialogue', 'Ask two core questions - Why? (YAGNI check) and Simpler? (KISS check)'. Describes a clear methodology with named techniques. | 3 / 3 |
Completeness | Clearly answers both what ('Clarify ambiguous requirements through focused dialogue before implementation') and when ('Use when requirements are unclear, features are complex (>2 days), or involve cross-team coordination'). Has explicit 'Use when...' clause with specific triggers. | 3 / 3 |
Trigger Term Quality | Includes some relevant terms like 'requirements', 'unclear', 'complex', 'cross-team coordination', but uses technical jargon (YAGNI, KISS) that users may not naturally say. Missing common variations like 'spec', 'scope', 'planning', 'design discussion'. | 2 / 3 |
Distinctiveness Conflict Risk | Clear niche focused on pre-implementation requirement clarification with specific triggers (unclear requirements, >2 days complexity, cross-team). The YAGNI/KISS methodology makes it distinct from general planning or coding skills. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
39%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill has excellent workflow clarity with a well-defined iterative process and clear validation thresholds, but suffers from severe verbosity and poor content organization. The 300+ line document includes extensive templates and explanations that could be dramatically condensed or split into reference files, violating token efficiency principles.
Suggestions
Extract the PRD template into a separate `PRD_TEMPLATE.md` file and reference it, reducing the main skill by ~80 lines
Remove explanatory content Claude already knows (e.g., what constitutes vague requirements, how to ask clarifying questions) and focus only on the specific scoring rubric and process
Add a concrete before/after example showing a vague requirement transformed into a scored, clarified specification
Consolidate the DO/DON'T section and behavioral guidelines into a brief list of 3-4 key constraints rather than 14 separate bullet points
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~300 lines with significant redundancy. Explains obvious concepts Claude knows (what vague requirements are, how to ask questions), includes excessive template boilerplate, and repeats similar information across sections (e.g., the scoring rubric appears conceptually multiple times). | 1 / 3 |
Actionability | Provides concrete structure (scoring rubric, PRD template, question formats) but lacks executable code examples. The guidance is specific but template-heavy rather than demonstrating actual usage with real examples of transforming a vague requirement into a clear one. | 2 / 3 |
Workflow Clarity | Clear 4-step process with explicit validation checkpoint (score ≥ 90 before proceeding), feedback loops (iterate until threshold met), and well-defined transitions between phases. The workflow is unambiguous with clear decision points. | 3 / 3 |
Progressive Disclosure | Monolithic wall of text with no references to external files. The entire PRD template (~80 lines) is inline when it could be a separate reference file. No navigation structure or links to supplementary materials despite the content length warranting it. | 1 / 3 |
Total | 7 / 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.
- 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.