{"id":"cc952d50-0cb1-42db-81cc-5e8b80389e9d","shortId":"PLgqXU","kind":"skill","title":"requirements-clarity","tagline":"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 c","description":"# Requirements Clarity Skill\n\n## Description\n\nAutomatically transforms vague requirements into actionable PRDs through systematic clarification with a 100-point scoring system.\n\n\n## Instructions\n\nWhen invoked, detect vague requirements:\n\n1. **Vague Feature Requests**\n   - User says: \"add login feature\", \"implement payment\", \"create dashboard\"\n   - Missing: How, with what technology, what constraints?\n\n2. **Missing Technical Context**\n   - No technology stack mentioned\n   - No integration points identified\n   - No performance/security constraints\n\n3. **Incomplete Specifications**\n   - No acceptance criteria\n   - No success metrics\n   - No edge cases considered\n   - No error handling mentioned\n\n4. **Ambiguous Scope**\n   - Unclear boundaries (\"user management\" - what exactly?)\n   - No distinction between MVP and future enhancements\n   - Missing \"what's NOT included\"\n\n**Do NOT activate when**:\n- Specific file paths mentioned (e.g., \"auth.go:45\")\n- Code snippets included\n- Existing functions/classes referenced\n- Bug fixes with clear reproduction steps\n\n## Core Principles\n\n1. **Systematic Questioning**\n   - Ask focused, specific questions\n   - One category at a time (2-3 questions per round)\n   - Build on previous answers\n   - Avoid overwhelming users\n\n2. **Quality-Driven Iteration**\n   - Continuously assess clarity score (0-100)\n   - Identify gaps systematically\n   - Iterate until ≥ 90 points\n   - Document all clarification rounds\n\n3. **Actionable Output**\n   - Generate concrete specifications\n   - Include measurable acceptance criteria\n   - Provide executable phases\n   - Enable direct implementation\n\n## Clarification Process\n\n### Step 1: Initial Requirement Analysis\n\n**Input**: User's requirement description\n\n**Tasks**:\n1. Parse and understand core requirement\n2. Generate feature name (kebab-case format)\n3. Determine document version (default `1.0` unless user specifies otherwise)\n4. Ensure `./docs/prds/` exists for PRD output\n5. Perform initial clarity assessment (0-100)\n\n**Assessment Rubric**:\n```\nFunctional Clarity: /30 points\n- Clear inputs/outputs: 10 pts\n- User interaction defined: 10 pts\n- Success criteria stated: 10 pts\n\nTechnical Specificity: /25 points\n- Technology stack mentioned: 8 pts\n- Integration points identified: 8 pts\n- Constraints specified: 9 pts\n\nImplementation Completeness: /25 points\n- Edge cases considered: 8 pts\n- Error handling mentioned: 9 pts\n- Data validation specified: 8 pts\n\nBusiness Context: /20 points\n- Problem statement clear: 7 pts\n- Target users identified: 7 pts\n- Success metrics defined: 6 pts\n```\n\n**Initial Response Format**:\n```markdown\nI understand your requirement. Let me help you refine this specification.\n\n**Current Clarity Score**: X/100\n\n**Clear Aspects**:\n- [List what's clear]\n\n**Needs Clarification**:\n- [List gaps]\n\nLet me systematically clarify these points...\n```\n\n### Step 2: Gap Analysis\n\nIdentify missing information across four dimensions:\n\n**1. Functional Scope**\n- What is the core functionality?\n- What are the boundaries?\n- What is out of scope?\n- What are edge cases?\n\n**2. User Interaction**\n- How do users interact?\n- What are the inputs?\n- What are the outputs?\n- What are success/failure scenarios?\n\n**3. Technical Constraints**\n- Performance requirements?\n- Compatibility requirements?\n- Security considerations?\n- Scalability needs?\n\n**4. Business Value**\n- What problem does this solve?\n- Who are the target users?\n- What are success metrics?\n- What is the priority?\n\n### Step 3: Interactive Clarification\n\n**Question Strategy**:\n1. Start with highest-impact gaps\n2. Ask 2-3 questions per round\n3. Build context progressively\n4. Use user's language\n5. Provide examples when helpful\n\n**Question Format**:\n```markdown\nI need to clarify the following points to complete the requirements document:\n\n1. **[Category]**: [Specific question]?\n   - For example: [Example if helpful]\n\n2. **[Category]**: [Specific question]?\n\n3. **[Category]**: [Specific question]?\n\nPlease provide your answers, and I'll continue refining the PRD.\n```\n\n**After Each User Response**:\n1. Update clarity score\n2. Capture new information in the working PRD outline\n3. Identify remaining gaps\n4. If score < 90: Continue with next round of questions\n5. If score ≥ 90: Proceed to PRD generation\n\n**Score Update Format**:\n```markdown\nThank you for the additional information!\n\n**Clarity Score Update**: X/100 → Y/100\n\n**New Clarified Content**:\n- [Summarize new information]\n\n**Remaining Points to Clarify**:\n- [List remaining gaps if score < 90]\n\n[If score < 90: Continue with next round of questions]\n[If score ≥ 90: \"Perfect! I will now generate the complete PRD document...\"]\n```\n\n### Step 4: PRD Generation\n\nOnce clarity score ≥ 90, generate comprehensive PRD.\n\n**Output File**:\n\n1. **Final PRD**: `./docs/prds/{feature_name}-v{version}-prd.md`\n\nUse the `Write` tool to create or update this file. Derive `{version}` from the document version recorded in the PRD (default `1.0`).\n\n## PRD Document Structure\n\n```markdown\n# {Feature Name} - Product Requirements Document (PRD)\n\n## Requirements Description\n\n### Background\n- **Business Problem**: [Describe the business problem to solve]\n- **Target Users**: [Target user groups]\n- **Value Proposition**: [Value this feature brings]\n\n### Feature Overview\n- **Core Features**: [List of main features]\n- **Feature Boundaries**: [What is and isn't included]\n- **User Scenarios**: [Typical usage scenarios]\n\n### Detailed Requirements\n- **Input/Output**: [Specific input/output specifications]\n- **User Interaction**: [User operation flow]\n- **Data Requirements**: [Data structures and validation rules]\n- **Edge Cases**: [Edge case handling]\n\n## Design Decisions\n\n### Technical Approach\n- **Architecture Choice**: [Technical architecture decisions and rationale]\n- **Key Components**: [List of main technical components]\n- **Data Storage**: [Data models and storage solutions]\n- **Interface Design**: [API/interface specifications]\n\n### Constraints\n- **Performance Requirements**: [Response time, throughput, etc.]\n- **Compatibility**: [System compatibility requirements]\n- **Security**: [Security considerations]\n- **Scalability**: [Future expansion considerations]\n\n### Risk Assessment\n- **Technical Risks**: [Potential technical risks and mitigation plans]\n- **Dependency Risks**: [External dependencies and alternatives]\n- **Schedule Risks**: [Timeline risks and response strategies]\n\n## Acceptance Criteria\n\n### Functional Acceptance\n- [ ] Feature 1: [Specific acceptance conditions]\n- [ ] Feature 2: [Specific acceptance conditions]\n- [ ] Feature 3: [Specific acceptance conditions]\n\n### Quality Standards\n- [ ] Code Quality: [Code standards and review requirements]\n- [ ] Test Coverage: [Testing requirements and coverage]\n- [ ] Performance Metrics: [Performance test pass criteria]\n- [ ] Security Review: [Security review requirements]\n\n### User Acceptance\n- [ ] User Experience: [UX acceptance criteria]\n- [ ] Documentation: [Documentation delivery requirements]\n- [ ] Training Materials: [If needed, training material requirements]\n\n## Execution Phases\n\n### Phase 1: Preparation\n**Goal**: Environment preparation and technical validation\n- [ ] Task 1: [Specific task description]\n- [ ] Task 2: [Specific task description]\n- **Deliverables**: [Phase deliverables]\n- **Time**: [Estimated time]\n\n### Phase 2: Core Development\n**Goal**: Implement core functionality\n- [ ] Task 1: [Specific task description]\n- [ ] Task 2: [Specific task description]\n- **Deliverables**: [Phase deliverables]\n- **Time**: [Estimated time]\n\n### Phase 3: Integration & Testing\n**Goal**: Integration and quality assurance\n- [ ] Task 1: [Specific task description]\n- [ ] Task 2: [Specific task description]\n- **Deliverables**: [Phase deliverables]\n- **Time**: [Estimated time]\n\n### Phase 4: Deployment\n**Goal**: Release and monitoring\n- [ ] Task 1: [Specific task description]\n- [ ] Task 2: [Specific task description]\n- **Deliverables**: [Phase deliverables]\n- **Time**: [Estimated time]\n\n---\n\n**Document Version**: 1.0\n**Created**: {timestamp}\n**Clarification Rounds**: {clarification_rounds}\n**Quality Score**: {quality_score}/100\n```\n\n## Behavioral Guidelines\n\n### DO\n- Ask specific, targeted questions\n- Build on previous answers\n- Provide examples to guide users\n- Maintain conversational tone\n- Summarize clarification rounds within the PRD\n- Use clear, professional English\n- Generate concrete specifications\n- Stay in clarification mode until score ≥ 90\n\n### DON'T\n- Ask all questions at once\n- Make assumptions without confirmation\n- Generate PRD before 90+ score\n- Skip any required sections\n- Use vague or abstract language\n- Proceed without user responses\n- Exit skill mode prematurely\n\n## Success Criteria\n\n- Clarity score ≥ 90/100\n- All PRD sections complete with substance\n- Acceptance criteria checklistable (using `- [ ]` format)\n- Execution phases actionable with concrete tasks\n- User approves final PRD\n- Ready for development handoff","tags":["requirements","clarity","agent","toolkit","softaworks","agent-skills","automation","claude","claude-code","coding-agent","development"],"capabilities":["skill","source-softaworks","skill-requirements-clarity","topic-agent-skills","topic-automation","topic-claude","topic-claude-code","topic-coding-agent","topic-development"],"categories":["agent-toolkit"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/softaworks/agent-toolkit/requirements-clarity","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add softaworks/agent-toolkit","source_repo":"https://github.com/softaworks/agent-toolkit","install_from":"skills.sh"}},"qualityScore":"0.700","qualityRationale":"deterministic score 0.70 from registry signals: · indexed on github topic:agent-skills · 1689 github stars · SKILL.md body (8,963 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-03T00:52:50.866Z","embedding":null,"createdAt":"2026-04-18T21:54:45.807Z","updatedAt":"2026-05-03T00:52:50.866Z","lastSeenAt":"2026-05-03T00:52:50.866Z","tsv":"'-100':201,279 '-3':180,489 '/100':1006 '/20':339 '/25':302,320 '/30':284 '/docs/prds':268,657 '0':200,278 '1':70,167,232,242,401,479,522,554,654,836,897,906,930,955,978 '1.0':261,684,995 '10':288,293,298 '100':60 '2':20,90,179,191,248,392,422,486,488,531,558,841,911,922,935,960,983 '3':105,213,256,441,474,493,535,567,846,946 '4':122,266,452,497,571,642,971 '5':273,502,581 '6':354 '7':344,349 '8':307,312,325,335 '9':316,330 '90':207,574,584,619,622,631,648,1045,1060 '90/100':1083 'abstract':1069 'accept':109,221,831,834,838,843,848,877,881,1090 'across':398 'action':53,214,1097 'activ':145 'add':76 'addit':597 'altern':823 'ambigu':5,123 'analysi':235,394 'answer':187,542,1017 'api/interface':788 'approach':764 'approv':1102 'architectur':765,768 'ask':28,170,487,1010,1048 'aspect':376 'assess':197,277,280,809 'assumpt':1054 'assur':953 'auth.go:45':152 'automat':48 'avoid':188 'background':697 'behavior':1007 'boundari':126,412,726 'bring':716 'bug':159 'build':184,494,1014 'busi':337,453,698,702 'c':43 'captur':559 'case':116,254,323,421,757,759 'categori':175,523,532,536 'check':34,38 'checklist':1092 'choic':766 'clarif':57,211,229,382,476,998,1000,1027,1041 'clarifi':4,388,513,605,613 'clariti':3,41,45,198,276,283,372,556,599,646,1081 'clear':162,286,343,375,380,1033 'code':153,852,854 'compat':446,797,799 'complet':319,518,638,1087 'complex':19 'compon':773,778 'comprehens':650 'concret':217,1037,1099 'condit':839,844,849 'confirm':1056 'consid':117,324 'consider':449,803,807 'constraint':89,104,314,443,790 'content':606 'context':93,338,495 'continu':196,546,575,623 'convers':1024 'coordin':27 'core':30,165,246,407,719,923,927 'coverag':860,864 'creat':81,668,996 'criteria':110,222,296,832,870,882,1080,1091 'cross':25 'cross-team':24 'current':371 'dashboard':82 'data':332,749,751,779,781 'day':21 'decis':762,769 'default':260,683 'defin':292,353 'deliver':915,917,939,941,964,966,987,989 'deliveri':885 'depend':818,821 'deploy':972 'deriv':673 'describ':700 'descript':47,240,696,909,914,933,938,958,963,981,986 'design':761,787 'detail':738 'detect':67 'determin':257 'develop':924,1107 'dialogu':9 'dimens':400 'direct':227 'distinct':132 'document':209,258,521,640,677,686,693,883,884,993 'driven':194 'e.g':151 'edg':115,322,420,756,758 'enabl':226 'english':1035 'enhanc':137 'ensur':40,267 'environ':900 'error':119,327 'estim':919,943,968,991 'etc':796 'exact':130 'exampl':504,527,528,1019 'execut':224,894,1095 'exist':156,269 'exit':1075 'expans':806 'experi':879 'extern':820 'featur':17,72,78,250,658,689,715,717,720,724,725,835,840,845 'file':148,653,672 'final':655,1103 'fix':160 'flow':748 'focus':8,171 'follow':515 'format':255,358,508,591,1094 'four':399 'function':282,402,408,833,928 'functions/classes':157 'futur':136,805 'gap':203,384,393,485,570,616 'generat':216,249,588,636,644,649,1036,1057 'goal':899,925,949,973 'group':710 'guid':1021 'guidelin':1008 'handl':120,328,760 'handoff':1108 'help':366,506,530 'highest':483 'highest-impact':482 'identifi':101,202,311,348,395,568 'impact':484 'implement':11,79,228,318,926 'includ':142,155,219,732 'incomplet':106 'inform':397,561,598,609 'initi':233,275,356 'input':236,432 'input/output':740,742 'inputs/outputs':287 'instruct':64 'integr':99,309,947,950 'interact':291,424,428,475,745 'interfac':786 'invok':66 'involv':23 'isn':730 'iter':195,205 'kebab':253 'kebab-cas':252 'key':772 'kiss':37 'languag':501,1070 'let':364,385 'list':377,383,614,721,774 'll':545 'login':77 'main':723,776 'maintain':1023 'make':1053 'manag':128 'markdown':359,509,592,688 'materi':888,892 'measur':220 'mention':97,121,150,306,329 'metric':113,352,468,866 'miss':83,91,138,396 'mitig':816 'mode':1042,1077 'model':782 'monitor':976 'mvp':134 'name':251,659,690 'need':381,451,511,890 'new':560,604,608 'next':577,625 'one':174 'oper':747 'otherwis':265 'outlin':566 'output':215,272,436,652 'overview':718 'overwhelm':189 'pars':243 'pass':869 'path':149 'payment':80 'per':182,491 'perfect':632 'perform':274,444,791,865,867 'performance/security':103 'phase':225,895,896,916,921,940,945,965,970,988,1096 'plan':817 'pleas':539 'point':61,100,208,285,303,310,321,340,390,516,611 'potenti':812 'prd':271,549,565,587,639,643,651,656,682,685,694,1031,1058,1085,1104 'prd.md':662 'prds':54 'prematur':1078 'prepar':898,901 'previous':186,1016 'principl':166 'prioriti':472 'problem':341,456,699,703 'proceed':585,1071 'process':230 'product':691 'profession':1034 'progress':496 'proposit':712 'provid':223,503,540,1018 'pts':289,294,299,308,313,317,326,331,336,345,350,355 'qualiti':193,850,853,952,1002,1004 'quality-driven':192 'question':31,169,173,181,477,490,507,525,534,538,580,628,1013,1050 'rational':771 'readi':1105 'record':679 'referenc':158 'refin':368,547 'releas':974 'remain':569,610,615 'reproduct':163 'request':73 'requir':2,6,14,44,51,69,234,239,247,363,445,447,520,692,695,739,750,792,800,858,862,875,886,893,1064 'requirements-clar':1 'respons':357,553,793,829,1074 'review':857,872,874 'risk':808,811,814,819,825,827 'round':183,212,492,578,626,999,1001,1028 'rubric':281 'rule':755 'say':75 'scalabl':450,804 'scenario':440,734,737 'schedul':824 'scope':124,403,417 'score':62,199,373,557,573,583,589,600,618,621,630,647,1003,1005,1044,1061,1082 'section':1065,1086 'secur':448,801,802,871,873 'simpler':36 'skill':46,1076 'skill-requirements-clarity' 'skip':1062 'snippet':154 'solut':785 'solv':459,705 'source-softaworks' 'specif':107,147,172,218,301,370,524,533,537,741,743,789,837,842,847,907,912,931,936,956,961,979,984,1011,1038 'specifi':264,315,334 'stack':96,305 'standard':851,855 'start':480 'state':297 'statement':342 'stay':1039 'step':164,231,391,473,641 'storag':780,784 'strategi':478,830 'structur':687,752 'substanc':1089 'success':112,295,351,467,1079 'success/failure':439 'summar':607,1026 'system':63,798 'systemat':56,168,204,387 'target':346,463,706,708,1012 'task':241,905,908,910,913,929,932,934,937,954,957,959,962,977,980,982,985,1100 'team':26 'technic':92,300,442,763,767,777,810,813,903 'technolog':87,95,304 'test':859,861,868,948 'thank':593 'throughput':795 'time':178,794,918,920,942,944,967,969,990,992 'timelin':826 'timestamp':997 'tone':1025 'tool':666 'topic-agent-skills' 'topic-automation' 'topic-claude' 'topic-claude-code' 'topic-coding-agent' 'topic-development' 'train':887,891 'transform':49 'two':29 'typic':735 'unclear':16,125 'understand':245,361 'unless':262 'updat':555,590,601,670 'usag':736 'use':12,498,663,1032,1066,1093 'user':74,127,190,237,263,290,347,423,427,464,499,552,707,709,733,744,746,876,878,1022,1073,1101 'ux':880 'v':660 'vagu':50,68,71,1067 'valid':333,754,904 'valu':454,711,713 'version':259,661,674,678,994 'within':1029 'without':1055,1072 'work':564 'write':665 'x/100':374,602 'y/100':603 'yagni':33","prices":[{"id":"c6ad2491-07ea-4068-92b0-cddb3a7afdc2","listingId":"cc952d50-0cb1-42db-81cc-5e8b80389e9d","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"softaworks","category":"agent-toolkit","install_from":"skills.sh"},"createdAt":"2026-04-18T21:54:45.807Z"}],"sources":[{"listingId":"cc952d50-0cb1-42db-81cc-5e8b80389e9d","source":"github","sourceId":"softaworks/agent-toolkit/requirements-clarity","sourceUrl":"https://github.com/softaworks/agent-toolkit/tree/main/skills/requirements-clarity","isPrimary":false,"firstSeenAt":"2026-04-18T21:54:45.807Z","lastSeenAt":"2026-05-03T00:52:50.866Z"}],"details":{"listingId":"cc952d50-0cb1-42db-81cc-5e8b80389e9d","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"softaworks","slug":"requirements-clarity","github":{"repo":"softaworks/agent-toolkit","stars":1689,"topics":["agent-skills","ai","automation","claude","claude-code","coding-agent","development"],"license":"mit","html_url":"https://github.com/softaworks/agent-toolkit","pushed_at":"2026-03-05T16:46:24Z","description":"A curated collection of skills for AI coding agents. Skills are packaged instructions and scripts that extend agent capabilities across development, documentation, planning, and professional workflows.","skill_md_sha":"87e59559bc84e18e7ab5743667dedb24d825259a","skill_md_path":"skills/requirements-clarity/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/softaworks/agent-toolkit/tree/main/skills/requirements-clarity"},"layout":"multi","source":"github","category":"agent-toolkit","frontmatter":{"name":"requirements-clarity","description":"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."},"skills_sh_url":"https://skills.sh/softaworks/agent-toolkit/requirements-clarity"},"updatedAt":"2026-05-03T00:52:50.866Z"}}