{"id":"fc0a6aa2-d845-44fa-905a-259673475c1a","shortId":"RpcQFd","kind":"skill","title":"draft-spec","tagline":"Guide a collaborative discussion that produces a specification document at .turbo/specs/<slug>.md. Use when the user asks to \"draft a spec\", \"create a spec\", \"write a spec\", \"discuss a project plan\", \"spec out a project\", \"design a system\", \"let's plan this project\", \"help me sco","description":"# Draft Spec\n\nGuide a collaborative discussion to explore a project idea, then synthesize the conversation into a comprehensive specification at `.turbo/specs/<slug>.md`.\n\n## Task Tracking\n\nAt the start, use `TaskCreate` to create a task for each step:\n\n1. Capture the vision and pick a slug\n2. Consult task-specific skills and docs\n3. Deep-dive discussion\n4. Draft the spec\n5. Resolve open questions\n6. Present and finalize\n\n## Step 1: Capture the Vision and Pick a Slug\n\nAbsorb whatever the user has provided — a sentence, a paragraph, a brain dump. Do not interrupt or ask questions yet. Restate the vision back in two or three sentences to confirm understanding.\n\nPick a slug for the spec file derived from the project or feature name:\n\n- Lowercase\n- Replace non-alphanumeric characters with hyphens\n- Collapse consecutive hyphens\n- Trim leading and trailing hyphens\n- Truncate to 40 characters at a word boundary\n\nExample: \"Photo Sorter v2\" → `photo-sorter-v2`. The user may pass an explicit slug; if so, honor it.\n\nIf `.turbo/specs/<slug>.md` already exists, use `AskUserQuestion` to ask whether to overwrite, append a numeric suffix (`-2`, `-3`, ...), or pick a different slug.\n\nState the chosen slug and the resulting spec path before continuing.\n\nThen use `AskUserQuestion` to ask 1-4 focused opening questions targeting the biggest unknowns. Skip anything the user already answered. Prioritize from:\n\n- What problem does this solve, and for whom?\n- Is this greenfield or does existing code/infrastructure exist?\n- Are there strong technology preferences or constraints?\n- What does the MVP look like versus the full vision?\n- Are there hard deadlines, budget limits, or team size constraints?\n\n## Step 2: Consult Task-Specific Skills and Docs\n\nGround architecture and tech-stack choices in current reality before the deep-dive discussion.\n\n1. **Scan for matching skills.** Compare the vision and opening-question answers against available skill trigger descriptions. For each unambiguous match, run the skill via the Skill tool. This loads decision-level guidance (idiomatic patterns, known pitfalls, version constraints) before architectural choices are made. If unsure, do not load.\n2. **Look up library or framework docs.** For any library, framework, or platform the user mentioned or the project clearly needs, query documentation MCP tools (or WebSearch as a fallback) when the decision hinges on current capabilities, supported versions, or known constraints.\n\nKeep findings at the decision level: what tools can do, which approaches are idiomatic, which versions to target. Do not embed specific API signatures or code snippets into the spec. Those belong in implementation-time skill loads.\n\n## Step 3: Deep-Dive Discussion\n\nExplore the project through multi-turn conversation. Cover these categories over the course of the discussion — track coverage internally but do not present them as a rigid checklist. Follow the user's energy and weave topics in naturally.\n\n| Category | What to explore |\n|---|---|\n| **Users and personas** | Who uses this? Goals, pain points, technical sophistication |\n| **Core features** | Primary capabilities and user-facing workflows |\n| **Architecture** | Client/server split, monolith vs services, real-time needs, offline support |\n| **Tech stack** | Languages, frameworks, databases, hosting — preferences and constraints |\n| **Data model** | Key entities, relationships, storage strategy |\n| **Integrations** | Third-party APIs, auth providers, external data sources |\n| **Non-functional requirements** | Performance, security, accessibility, i18n, compliance |\n| **MVP scope** | What ships first? What is explicitly deferred? |\n| **Open questions** | Unknowns needing research, prototyping, or external input |\n\n### Discussion Guidelines\n\n- Use `AskUserQuestion` to ask one or two questions at a time, not a wall of questions. Use options with descriptions to frame trade-offs and offer concrete suggestions. Use `multiSelect` when choices are not mutually exclusive.\n- When the user gives a short answer, probe deeper before moving on\n- Offer concrete suggestions and trade-off analysis — be a collaborator, not an interviewer\n- If the user says \"you decide\" or \"what do you recommend\", make a clear recommendation with reasoning\n- When all categories have sufficient depth or the user signals readiness, confirm before moving to drafting\n\n## Step 4: Draft the Spec\n\nSynthesize the consulted skill and doc context plus the entire discussion into `.turbo/specs/<slug>.md` using the slug picked in Step 1. Structure the document organically based on what emerged in conversation:\n\n- Include only sections with real substance — no placeholder filler\n- Use concrete details from the discussion, not vague generalizations\n- Where the user deferred a decision, capture it in an Open Questions section\n- Where recommendations were accepted, state them as decisions with brief rationale\n- Adapt the structure to the project — a CLI tool spec looks different from a SaaS platform spec\n- Trace every specified component (data model, API, utility, service) to at least one consumer in the spec. If a component exists only to \"support future work,\" either spec the future work concretely or defer the component.\n\nCreate the `.turbo/specs/` directory if it does not exist. Accept a different output path if the user provides one.\n\n## Step 5: Resolve Open Questions\n\nIf the spec's Open Questions section is empty, contains \"None,\" or does not exist, skip this step.\n\nFor each open question:\n\n1. Analyze the question against the spec, prior discussion, and consulted-docs context from Step 2. State the trade-offs of the leading options in plain text so the user can see the reasoning.\n2. Use `AskUserQuestion` to offer 2-3 concrete resolution options with short descriptions, plus a **Defer to implementation** option (leaves the question in Open Questions to be surfaced again when shells are expanded). Mark the strongest option \"(Recommended)\" and place it first.\n3. Fold the chosen answer into the relevant spec section and remove the question from Open Questions.\n\nIf the user selects \"Other\" and provides a freeform answer, accept it and proceed.\n\nDefault to resolving. Defer only when the answer genuinely needs codebase or pattern-survey context that is not yet available. If every question resolves, replace the Open Questions section with \"None.\"\n\n## Step 6: Present and Finalize\n\nPresent the draft to the user. Use `AskUserQuestion` to offer three paths:\n\n- **Approve** — spec is final\n- **Revise** — user specifies sections to change; apply edits and re-present\n- **Discuss more** — return to Step 3 for additional exploration, then re-draft\n\nAfter approval:\n\n> The spec is ready at the resolved spec path. To break it into shells, run `/draft-shells`.\n\n## Rules\n\n- Never skip Step 3 — even with extensive initial context, confirm understanding and probe gaps\n- The spec is the only output — do not create code, scaffolding, or other project files\n- If the project is trivially small (single-file script, simple config), say so and suggest skipping the spec process","tags":["draft","spec","turbo","tobihagemann","agent-skills","claude-code","claude-skills","developer-tools","skills"],"capabilities":["skill","source-tobihagemann","skill-draft-spec","topic-agent-skills","topic-claude-code","topic-claude-skills","topic-developer-tools","topic-skills"],"categories":["turbo"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/tobihagemann/turbo/draft-spec","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add tobihagemann/turbo","source_repo":"https://github.com/tobihagemann/turbo","install_from":"skills.sh"}},"qualityScore":"0.590","qualityRationale":"deterministic score 0.59 from registry signals: · indexed on github topic:agent-skills · 280 github stars · SKILL.md body (7,120 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-04-22T00:54:09.147Z","embedding":null,"createdAt":"2026-04-18T22:03:41.407Z","updatedAt":"2026-04-22T00:54:09.147Z","lastSeenAt":"2026-04-22T00:54:09.147Z","tsv":"'-2':233 '-3':234,923 '-4':257 '/draft-shells':1085 '1':86,120,256,341,729,881 '2':94,317,392,897,917,922 '3':102,473,959,1060,1090 '4':107,705 '40':192 '5':111,855 '6':115,1023 'absorb':128 'accept':774,844,986 'access':585 'adapt':782 'addit':1062 'alphanumer':178 'alreadi':220,269 'analysi':664 'analyz':882 'answer':270,353,651,963,985,997 'anyth':266 'api':456,573,805 'append':229 'appli':1049 'approach':445 'approv':1039,1069 'architectur':326,383,541 'ask':20,145,225,255,611 'askuserquest':223,253,609,919,1034 'auth':574 'avail':355,1010 'back':151 'base':734 'belong':465 'biggest':263 'boundari':197 'brain':139 'break':1080 'brief':780 'budget':310 'capabl':428,535 'captur':87,121,764 'categori':488,517,690 'chang':1048 'charact':179,193 'checklist':506 'choic':331,384,640 'chosen':242,962 'clear':411,684 'cli':789 'client/server':542 'code':459,1110 'code/infrastructure':287 'codebas':1000 'collabor':6,54,667 'collaps':182 'compar':346 'complianc':587 'compon':802,818,834 'comprehens':67 'concret':635,658,750,830,924 'config':1127 'confirm':158,699,1096 'consecut':183 'constraint':295,315,381,433,561 'consult':95,318,711,892 'consulted-doc':891 'consum':812 'contain':868 'context':715,894,1005,1095 'continu':250 'convers':64,485,739 'core':532 'cours':491 'cover':486 'coverag':496 'creat':25,80,835,1109 'current':333,427 'data':562,577,803 'databas':557 'deadlin':309 'decid':676 'decis':373,424,438,763,778 'decision-level':372 'deep':104,338,475 'deep-div':103,337,474 'deeper':653 'default':990 'defer':596,761,832,932,993 'depth':693 'deriv':167 'descript':358,627,929 'design':39 'detail':751 'differ':238,793,846 'directori':838 'discuss':7,31,55,106,340,477,494,606,719,754,889,1055 'dive':105,339,476 'doc':101,324,398,714,893 'document':12,414,732 'draft':2,22,50,108,703,706,1029,1067 'draft-spec':1 'dump':140 'edit':1050 'either':825 'emb':454 'emerg':737 'empti':867 'energi':511 'entir':718 'entiti':565 'even':1091 'everi':800,1012 'exampl':198 'exclus':644 'exist':221,286,288,819,843,873 'expand':949 'explicit':211,595 'explor':57,478,520,1063 'extens':1093 'extern':576,604 'face':539 'fallback':421 'featur':172,533 'file':166,1115,1124 'filler':748 'final':118,1026,1042 'find':435 'first':592,958 'focus':258 'fold':960 'follow':507 'frame':629 'framework':397,402,556 'freeform':984 'full':304 'function':581 'futur':823,828 'gap':1100 'general':757 'genuin':998 'give':648 'goal':527 'greenfield':283 'ground':325 'guid':4,52 'guidanc':375 'guidelin':607 'hard':308 'help':47 'hing':425 'honor':215 'host':558 'hyphen':181,184,189 'i18n':586 'idea':60 'idiomat':376,447 'implement':468,934 'implementation-tim':467 'includ':740 'initi':1094 'input':605 'integr':569 'intern':497 'interrupt':143 'interview':670 'keep':434 'key':564 'known':378,432 'languag':555 'lead':186,905 'least':810 'leav':936 'let':42 'level':374,439 'librari':395,401 'like':301 'limit':311 'load':371,391,471 'look':300,393,792 'lowercas':174 'made':386 'make':682 'mark':950 'match':344,362 'may':208 'mcp':415 'md':15,71,219,722 'mention':407 'model':563,804 'monolith':544 'move':655,701 'multi':483 'multi-turn':482 'multiselect':638 'mutual':643 'mvp':299,588 'name':173 'natur':516 'need':412,550,600,999 'never':1087 'non':177,580 'non-alphanumer':176 'non-funct':579 'none':869,1021 'numer':231 'off':632,902 'offer':634,657,921,1036 'offlin':551 'one':612,811,853 'open':113,259,351,597,768,857,863,879,940,974,1017 'opening-quest':350 'option':625,906,926,935,953 'organ':733 'output':847,1106 'overwrit':228 'pain':528 'paragraph':137 'parti':572 'pass':209 'path':248,848,1038,1078 'pattern':377,1003 'pattern-survey':1002 'perform':583 'persona':523 'photo':199,203 'photo-sorter-v2':202 'pick':91,125,160,236,726 'pitfal':379 'place':956 'placehold':747 'plain':908 'plan':34,44 'platform':404,797 'plus':716,930 'point':529 'prefer':293,559 'present':116,501,1024,1027,1054 'primari':534 'prior':888 'priorit':271 'probe':652,1099 'problem':274 'proceed':989 'process':1135 'produc':9 'project':33,38,46,59,170,410,480,787,1114,1118 'prototyp':602 'provid':133,575,852,982 'queri':413 'question':114,146,260,352,598,615,623,769,858,864,880,884,938,941,972,975,1013,1018 'rational':781 're':1053,1066 're-draft':1065 're-pres':1052 'readi':698,1073 'real':548,744 'real-tim':547 'realiti':334 'reason':687,916 'recommend':681,685,772,954 'relationship':566 'relev':966 'remov':970 'replac':175,1015 'requir':582 'research':601 'resolut':925 'resolv':112,856,992,1014,1076 'restat':148 'result':246 'return':1057 'revis':1043 'rigid':505 'rule':1086 'run':363,1084 'saa':796 'say':674,1128 'scaffold':1111 'scan':342 'sco':49 'scope':589 'script':1125 'section':742,770,865,968,1019,1046 'secur':584 'see':914 'select':979 'sentenc':135,156 'servic':546,807 'shell':947,1083 'ship':591 'short':650,928 'signal':697 'signatur':457 'simpl':1126 'singl':1123 'single-fil':1122 'size':314 'skill':99,322,345,356,365,368,470,712 'skill-draft-spec' 'skip':265,874,1088,1132 'slug':93,127,162,212,239,243,725 'small':1121 'snippet':460 'solv':277 'sophist':531 'sorter':200,204 'sourc':578 'source-tobihagemann' 'spec':3,24,27,30,35,51,110,165,247,463,708,791,798,815,826,861,887,967,1040,1071,1077,1102,1134 'specif':11,68,98,321,455 'specifi':801,1045 'split':543 'stack':330,554 'start':76 'state':240,775,898 'step':85,119,316,472,704,728,854,876,896,1022,1059,1089 'storag':567 'strategi':568 'strong':291 'strongest':952 'structur':730,784 'substanc':745 'suffici':692 'suffix':232 'suggest':636,659,1131 'support':429,552,822 'surfac':944 'survey':1004 'synthes':62,709 'system':41 'target':261,451 'task':72,82,97,320 'task-specif':96,319 'taskcreat':78 'team':313 'tech':329,553 'tech-stack':328 'technic':530 'technolog':292 'text':909 'third':571 'third-parti':570 'three':155,1037 'time':469,549,618 'tool':369,416,441,790 'topic':514 'topic-agent-skills' 'topic-claude-code' 'topic-claude-skills' 'topic-developer-tools' 'topic-skills' 'trace':799 'track':73,495 'trade':631,662,901 'trade-off':630,661,900 'trail':188 'trigger':357 'trim':185 'trivial':1120 'truncat':190 'turbo/specs':14,70,218,721,837 'turn':484 'two':153,614 'unambigu':361 'understand':159,1097 'unknown':264,599 'unsur':388 'use':16,77,222,252,525,608,624,637,723,749,918,1033 'user':19,131,207,268,406,509,521,538,647,673,696,760,851,912,978,1032,1044 'user-fac':537 'util':806 'v2':201,205 'vagu':756 'version':380,430,449 'versus':302 'via':366 'vision':89,123,150,305,348 'vs':545 'wall':621 'weav':513 'websearch':418 'whatev':129 'whether':226 'word':196 'work':824,829 'workflow':540 'write':28 'yet':147,1009","prices":[{"id":"1602a1cc-f15a-4cab-b244-d13e8f4d2afc","listingId":"fc0a6aa2-d845-44fa-905a-259673475c1a","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"tobihagemann","category":"turbo","install_from":"skills.sh"},"createdAt":"2026-04-18T22:03:41.407Z"}],"sources":[{"listingId":"fc0a6aa2-d845-44fa-905a-259673475c1a","source":"github","sourceId":"tobihagemann/turbo/draft-spec","sourceUrl":"https://github.com/tobihagemann/turbo/tree/main/skills/draft-spec","isPrimary":false,"firstSeenAt":"2026-04-18T22:03:41.407Z","lastSeenAt":"2026-04-22T00:54:09.147Z"}],"details":{"listingId":"fc0a6aa2-d845-44fa-905a-259673475c1a","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"tobihagemann","slug":"draft-spec","github":{"repo":"tobihagemann/turbo","stars":280,"topics":["agent-skills","claude-code","claude-skills","developer-tools","skills"],"license":"mit","html_url":"https://github.com/tobihagemann/turbo","pushed_at":"2026-04-21T12:22:12Z","description":"A composable dev process for Claude Code, packaged as modular skills.","skill_md_sha":"15d47967f84446f1f15c276b7102f8de19e234e7","skill_md_path":"skills/draft-spec/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/tobihagemann/turbo/tree/main/skills/draft-spec"},"layout":"multi","source":"github","category":"turbo","frontmatter":{"name":"draft-spec","description":"Guide a collaborative discussion that produces a specification document at .turbo/specs/<slug>.md. Use when the user asks to \"draft a spec\", \"create a spec\", \"write a spec\", \"discuss a project plan\", \"spec out a project\", \"design a system\", \"let's plan this project\", \"help me scope this\", \"architect a solution\", or \"let's discuss before building\"."},"skills_sh_url":"https://skills.sh/tobihagemann/turbo/draft-spec"},"updatedAt":"2026-04-22T00:54:09.147Z"}}