{"id":"c9eb22ef-5151-4aa0-9021-e758819668ac","shortId":"GwsuwM","kind":"skill","title":"draft-shells","tagline":"Decompose a specification file into shells with YAML frontmatter. Each shell captures the wiring invariants (Produces, Consumes, Covers) and high-level Implementation Steps without committing to file paths. Use when the user asks to \"draft shells\", \"create shells\", \"break spec in","description":"# Draft Shells\n\nDecompose a specification file into shells at `.turbo/shells/<spec-slug>-NN-<title>.md`. Each shell represents one unit of work for a separate Claude Code session.\n\n## Task Tracking\n\nAt the start, use `TaskCreate` to create a task for each step:\n\n1. Resolve the source spec\n2. Decompose into shells\n3. Resolve open questions\n4. Write shell files\n5. Present summary\n\n## Step 1: Resolve the Source Spec\n\nDetermine which spec to decompose using these rules in order:\n\n1. **Explicit path** — If the user passed a file path, use it\n2. **Explicit slug** — If a slug was passed, resolve to `.turbo/specs/<slug>.md`\n3. **Single file** — Glob `.turbo/specs/*.md`. If exactly one file exists, use it\n4. **Most recent** — If multiple files exist, use the most recently modified\n5. **Legacy fallback** — If `.turbo/specs/` does not exist but `.turbo/spec.md` exists, use it\n6. **Nothing found** — If no spec exists, tell the user to run `/draft-spec` first and stop\n\nThe slug of the resolved spec becomes the prefix for shell file names: a spec at `.turbo/specs/<slug>.md` produces shells at `.turbo/shells/<slug>-NN-<title>.md`. For the legacy fallback, use slug `legacy`.\n\nState the resolved spec path and target shell directory before continuing.\n\nRead the spec and identify:\n- **Scope** — total surface area of work\n- **Work categories** — UI, backend, data layer, infrastructure, tests, documentation, tooling\n- **Spec requirements** — enumerate the distinct requirements so each can be tracked in a shell's Covers field\n- **Dependencies** — which pieces must exist before others can start\n- **Greenfield vs existing** — is there an established codebase to work within\n- **Open questions** — decisions the spec deferred that will need to be answered at implementation time\n\n## Step 2: Decompose Into Shells\n\nSplit the spec into shells where each shell fits a single Claude Code context session.\n\n### Shell-Worthiness\n\nNot every spec item earns its own shell. A spec item earns a shell when either:\n\n- It has distinct Produces/Consumes boundaries with other shells (other shells build on what it produces, or it requires what another shell produces), or\n- It genuinely requires a full implementation session (meaningful pattern survey, non-trivial context, multiple coupled files).\n\nItems meeting neither criterion get folded into the most related shell's Implementation Steps. If several such items have no clear home, group them into a single \"minor fixes\" shell at the end.\n\nDo not default to one shell per spec item. Individual items are often too small for a focused session on their own. For each draft shell, ask whether it is a full focused implementation session — if not, fold it into the most coupled adjacent shell. A spec's suggested groupings are usually closer to right than a conservative further split. Equally, if no forcing condition (below) applies and the entire scope fits one session, a single shell is the right answer — do not invent dependencies to hit a multi-shell shape.\n\n**Forcing condition — atomic ripple.** When a breaking change to a shared interface requires every consumer across multiple modules to update in lockstep, the change and all consumer updates must land in one shell regardless of size. Splitting leaves intermediate states that break dependents.\n\n### Sizing\n\n- One shell = one logical unit of work (a feature, a subsystem, a layer)\n- Never split tightly-coupled pieces across shells (if UI + API + tests are inseparable, keep them together)\n- Split independent subsystems into separate shells\n- If a shell would touch more than ~15-20 files or span 3+ unrelated subsystems, split further\n- If the entire scope fits one session, produce a single shell\n- Each shell must leave the codebase fully integrated, with no components unreachable from the project's entry points\n- When a shell builds infrastructure that a later shell consumes, name the consumer explicitly in the Produces field\n\n### Ordering\n\nOrder by dependency, foundational work before dependent work:\n\n1. Setup and scaffolding (project init, config, CI)\n2. Data and domain layer (models, schemas, types)\n3. Core business logic\n4. API and service layer\n5. UI and frontend\n6. Integration and end-to-end concerns\n\nMitigate dead code risk in bottom-up ordering by bundling tightly-coupled producer/consumer pairs into the same shell, or having foundation shells include a minimal integration point (e.g., a single working endpoint or CLI command) that proves the code is reachable.\n\n### Wiring Invariants\n\nFor each shell, identify the structural contract with the rest of the decomposition:\n\n- **Produces** — What this shell creates that other shells (or the final system) can use. List concrete artifacts at the conceptual level: modules, types, endpoints, data models, UI screens, migration files. File paths are filled in at expansion time.\n- **Consumes** — What this shell depends on that must already exist. Either listed in a prior shell's Produces, or marked \"from existing codebase\" if it predates this decomposition. Every Consumes entry must be traceable to a source.\n- **Covers spec requirements** — Which spec sections or requirements this shell implements. The union of Covers across all shells must equal the set of spec requirements. For partial coverage, mark the entry `(partial: <what's deferred>)` and name the deferred work in that shell's Open Questions — a bare \"Covers §N\" for partial coverage breaks the invariant.\n\n### Shell Slug\n\nEach shell gets a slug derived from its title using spec slug rules (lowercase, hyphenated, ≤40 chars), prefixed with the shell number: `<spec-slug>-NN-<title-slug>`. The shell keeps this file name when `/expand-shell` fills it in.\n\nExample: spec slug `photo-sorter-v2`, Shell 3 titled \"Build duplicate detection\" → slug `photo-sorter-v2-03-build-duplicate-detection`, written to `.turbo/shells/photo-sorter-v2-03-build-duplicate-detection.md`.\n\n## Step 3: Resolve Open Questions\n\nIf no open questions emerged during decomposition or carried over from the spec, skip this step.\n\nFor each open question:\n\n1. Analyze the question against the spec, decomposition context, and any consulted references. 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 expansion** option (leaves the question on the relevant shell's Open Questions list). Mark the strongest option \"(Recommended)\" and place it first.\n3. If resolved, update the in-memory decomposition (Produces, Consumes, Covers, Implementation Steps) to reflect the answer. If deferred, record it against the relevant shell in the in-memory decomposition.\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.\n\nIf an answer would restructure the decomposition significantly (changes shell count, merges existing shells, or splits one shell into several), re-run Step 2 with the new constraint before continuing to Step 4.\n\n## Step 4: Write Shell Files\n\nCreate `.turbo/shells/` if it does not exist. For each shell, write a file at `.turbo/shells/<shell-slug>.md` using this template:\n\n````markdown\n---\nspec: <resolved spec path from Step 1>\ndepends_on: []\n---\n\n# Plan: <Shell Title>\n\n## Context\n\n<Why this work matters, drawn from relevant spec sections. Focus on the intended outcome. One or two paragraphs.>\n\n## Produces\n\n- <Conceptual artifact 1 — what it is, what it does>\n- <Conceptual artifact 2>\n- ...\n\n## Consumes\n\n- <Conceptual dependency 1 — from Shell N, or \"from existing codebase\">\n- <Conceptual dependency 2>\n- ...\n\n## Covers Spec Requirements\n\n- <Spec section or requirement ID>\n- <Spec section or requirement ID>\n- ...\n\n## Implementation Steps (High-Level)\n\n1. **<Step title>**\n   - <Description of what this step accomplishes at the conceptual level>\n2. **<Step title>**\n   - <Description>\n3. ...\n\n## Open Questions\n\n- <Question deferred from spec, to be answered at expansion time>\n- <Question>\n- ...\n\n## Expansion Deferred\n\nThe following are filled in when `/expand-shell` runs:\n\n- Pattern survey against the codebase state at implementation time\n- Concrete `file_path:line_number` references for each Implementation Step\n- Verification section with specific test commands and smoke checks\n- Context Files section with the files to read in full before editing\n````\n\n### Frontmatter Fields\n\n- **spec** — Absolute or relative path to the source spec\n- **depends_on** — List of shell file names (without `.md`) that must be expanded and implemented before this shell can be picked. Use `[]` for shells with no dependencies.\n\nExample `depends_on` for Shell 3 that depends on Shells 1 and 2:\n```yaml\ndepends_on: [photo-sorter-v2-01-setup, photo-sorter-v2-02-models]\n```\n\nIf a shell has no Open Questions, include the section with \"None\" so the structure stays consistent.\n\n## Step 5: Present Summary\n\nPresent a brief summary: number of shells, one-line description of each shell's scope, and any assumptions made about ambiguities. Tell the user the next step:\n\n> To start implementation, run `/pick-next-shell`. It will pick the next shell, expand it with a fresh pattern survey and concrete references, refine, self-improve, then halt. Run `/implement-plan` in a fresh session afterward.\n\nThen use the TaskList tool and proceed to any remaining task.\n\n## Rules\n\n- Never merge setup and finalization into the same shell\n- If the spec is ambiguous about what belongs together, split conservatively (smaller shells are safer than oversized ones)\n- Each shell must be self-contained with enough structural context (Context, Produces, Consumes, Covers) to understand the work without reading the full spec\n- Shell files are the only outputs. Do not modify the spec or project files.\n- Every Consumes entry must trace to a prior shell's Produces or to \"from existing codebase.\"\n- The union of all Covers fields must equal the set of spec requirements.","tags":["draft","shells","turbo","tobihagemann","agent-skills","claude-code","claude-skills","developer-tools","skills"],"capabilities":["skill","source-tobihagemann","skill-draft-shells","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-shells","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 (10,090 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.080Z","embedding":null,"createdAt":"2026-04-18T22:03:40.643Z","updatedAt":"2026-04-22T00:54:09.080Z","lastSeenAt":"2026-04-22T00:54:09.080Z","tsv":"'-20':606 '-3':1022 '/draft-spec':195 '/expand-shell':929,1256 '/implement-plan':1441 '/pick-next-shell':1417 '01':1356 '02':1362 '03':951 '1':85,106,121,671,984,1207,1217,1233,1346 '15':605 '2':90,133,315,679,1016,1021,1146,1234,1348 '3':94,145,610,687,941,960,1055,1235,1341 '4':98,158,691,1155,1157 '40':914 '5':102,170,696,1382 '6':183,700 'absolut':1301 'accept':1097 'across':533,581,856 'adjac':469 'afterward':1446 'alreadi':812 'ambigu':1406,1472 'analyz':985 'anoth':372 'answer':310,506,1072,1096,1108,1124,1244 'api':585,692 'appli':492 'area':249 'artifact':782,1206 'ask':37,452 'askuserquest':1018 'assumpt':1403 'atom':520 'avail':1121 'backend':255 'bare':888 'becom':205 'belong':1475 'bottom':714 'bottom-up':713 'boundari':357 'break':43,524,559,894 'brief':1387 'build':363,647,943,953 'build-duplicate-detect':952 'bundl':718 'busi':689 'captur':15 'carri':972 'categori':253 'chang':525,541,1130 'char':915 'check':1285 'ci':678 'claud':68,330 'clear':413 'cli':743 'closer':478 'code':69,331,710,748 'codebas':295,631,826,1111,1224,1262,1539 'command':744,1282 'commit':29 'compon':636 'conceptu':785,1205,1215 'concern':707 'concret':781,1023,1267,1432 'condit':490,519 'config':677 'conserv':483,1478 'consist':1380 'constraint':1150 'consult':995 'consum':20,532,544,653,656,804,833,1065,1214,1499,1525 'contain':1492 'context':332,389,992,1116,1185,1286,1496,1497 'continu':240,1152 'contract':759 'core':688 'count':1132 'coupl':391,468,579,721 'cover':21,277,841,855,889,1066,1225,1500,1544 'coverag':868,893 'creat':41,79,770,1161 'criterion':396 'data':256,680,790 'dead':709 'decis':301 'decompos':4,48,91,115,316 'decomposit':765,831,970,991,1063,1086,1128 'default':428,1101 'defer':304,875,879,1031,1074,1104,1239,1249 'depend':279,510,560,665,669,808,1182,1216,1309,1335,1337,1343,1350 'deriv':904 'descript':1028,1395 'detect':945,955 'determin':111 'directori':238 'distinct':266,355 'document':260 'domain':682 'draft':2,39,46,450 'draft-shel':1 'drawn':1190 'duplic':944,954 'e.g':737 'earn':341,348 'edit':1297 'either':352,814 'emerg':968 'end':425,704,706 'end-to-end':703 'endpoint':741,789 'enough':1494 'entir':495,617 'entri':642,834,871,1526 'enumer':264 'equal':486,860,1547 'establish':294 'everi':338,531,832,1524 'exact':152 'exampl':933,1336 'exist':155,164,177,180,189,283,290,813,825,1134,1167,1223,1538 'expand':1321,1424 'expans':802,1033,1246,1248 'explicit':122,134,657 'fallback':172,226 'featur':570 'field':278,661,1299,1545 'file':7,31,51,101,129,147,154,163,210,392,607,795,796,926,1160,1173,1268,1287,1291,1314,1511,1523 'fill':799,930,1253 'final':776,1463 'first':196,1054 'fit':327,497,619 'fix':421 'focus':443,458,1195 'fold':398,463 'follow':1251 'forc':489,518 'found':185 'foundat':666,730 'freeform':1095 'fresh':1428,1444 'frontend':699 'frontmatt':12,1298 'full':380,457,1295,1508 'fulli':632 'genuin':377,1109 'get':397,901 'glob':148 'greenfield':288 'group':415,475 'halt':1439 'high':24,1231 'high-level':23,1230 'hit':512 'home':414 'hyphen':913 'identifi':245,756 'implement':26,312,381,405,459,851,1067,1228,1265,1275,1323,1415 'improv':1437 'in-memori':1060,1083 'includ':732,1371 'independ':593 'individu':435 'infrastructur':258,648 'init':676 'insepar':588 'integr':633,701,735 'intend':1198 'interfac':529 'intermedi':556 'invari':18,752,896 'invent':509 'item':340,347,393,410,434,436 'keep':589,924 'land':547 'later':651 'layer':257,574,683,695 'lead':1004 'leav':555,629,1035 'legaci':171,225,229 'level':25,786,1232 'line':1270,1394 'list':780,815,1045,1311 'lockstep':539 'logic':565,690 'lowercas':912 'made':1404 'mark':823,869,1046 'markdown':1180 'matter':1189 'md':57,144,150,216,222,1176,1317 'meaning':383 'meet':394 'memori':1062,1085 'merg':1133,1460 'migrat':794 'minim':734 'minor':420 'mitig':708 'model':684,791,1363 'modifi':169,1518 'modul':535,787 'multi':515 'multi-shel':514 'multipl':162,390,534 'must':282,546,628,811,835,859,1319,1488,1527,1546 'n':890,1220 'name':211,654,877,927,1315 'need':307,1110 'neither':395 'never':575,1459 'new':1149 'next':1411,1422 'nn':56,221,921 'non':387 'non-trivi':386 'none':1375 'noth':184 'number':920,1271,1389 'off':1001 'offer':1020 'often':438 'one':61,153,430,498,549,562,564,620,1138,1200,1393,1485 'one-lin':1392 'open':96,299,885,962,966,982,1043,1236,1369 'option':1005,1025,1034,1049 'order':120,662,663,716 'other':285 'outcom':1199 'output':1515 'overs':1484 'pair':723 'paragraph':1203 'partial':867,872,892 'pass':127,140 'path':32,123,130,234,797,1269,1304 'pattern':384,1114,1258,1429 'pattern-survey':1113 'per':432 'photo':937,948,1353,1359 'photo-sorter-v2':936,947,1352,1358 'pick':1329,1420 'piec':281,580 'place':1052 'plain':1007 'plan':1184 'plus':1029 'point':643,736 'predat':829 'prefix':207,916 'present':103,1383,1385 'prior':818,1531 'proceed':1100,1453 'produc':19,217,367,374,622,660,766,821,1064,1204,1498,1534 'producer/consumer':722 'produces/consumes':356 'project':640,675,1522 'prove':746 'provid':1093 'question':97,300,886,963,967,983,987,1037,1044,1237,1238,1370 're':1143 're-run':1142 'reachabl':750 'read':241,1293,1506 'reason':1015 'recent':160,168 'recommend':1050 'record':1075 'refer':996,1272,1433 'refin':1434 'reflect':1070 'regardless':551 'relat':402,1303 'relev':1040,1079,1192 'remain':1456 'repres':60 'requir':263,267,370,378,530,843,848,865,1227,1552 'resolut':1024 'resolv':86,95,107,141,203,232,961,1057,1103 'rest':762 'restructur':1126 'right':480,505 'rippl':521 'risk':711 'rule':118,911,1458 'run':194,1144,1257,1416,1440 'safer':1482 'scaffold':674 'schema':685 'scope':246,496,618,1400 'screen':793 'section':846,1194,1278,1288,1373 'see':1013 'select':1090 'self':1436,1491 'self-contain':1490 'self-improv':1435 'separ':67,596 'servic':694 'session':70,333,382,444,460,499,621,1445 'set':862,1549 'setup':672,1357,1461 'sever':408,1141 'shape':517 'share':528 'shell':3,9,14,40,42,47,53,59,93,100,209,218,237,275,318,323,326,335,344,350,360,362,373,403,422,431,451,470,502,516,550,563,582,597,600,625,627,646,652,727,731,755,769,773,807,819,850,858,883,897,900,919,923,940,1041,1080,1131,1135,1139,1159,1170,1219,1313,1326,1332,1340,1345,1366,1391,1398,1423,1467,1480,1487,1510,1532 'shell-worthi':334 'short':1027 'signific':1129 'singl':146,329,419,501,624,739 'size':553,561 'skill' 'skill-draft-shells' 'skip':977 'slug':135,138,200,228,898,903,910,935,946 'small':440 'smaller':1479 'smoke':1284 'sorter':938,949,1354,1360 'sourc':88,109,840,1307 'source-tobihagemann' 'span':609 'spec':44,89,110,113,188,204,213,233,243,262,303,321,339,346,433,472,842,845,864,909,934,976,990,1181,1193,1226,1241,1300,1308,1470,1509,1520,1551 'specif':6,50,1280 'split':319,485,554,576,592,613,1137,1477 'start':75,287,1414 'state':230,557,997,1263 'stay':1379 'step':27,84,105,314,406,959,979,1068,1145,1154,1156,1229,1276,1381,1412 'stop':198 'strongest':1048 'structur':758,1378,1495 'subsystem':572,594,612 'suggest':474 'summari':104,1384,1388 'surfac':248 'survey':385,1115,1259,1430 'system':777 'target':236 'task':71,81,1457 'taskcreat':77 'tasklist':1450 'tell':190,1407 'templat':1179 'test':259,586,1281 'text':1008 'tight':578,720 'tightly-coupl':577,719 'time':313,803,1247,1266 'titl':907,942 'togeth':591,1476 'tool':261,1451 'topic-agent-skills' 'topic-claude-code' 'topic-claude-skills' 'topic-developer-tools' 'topic-skills' 'total':247 'touch':602 'trace':1528 'traceabl':837 'track':72,272 'trade':1000 'trade-off':999 'trivial':388 'turbo/shells':55,220,1162,1175 'turbo/shells/photo-sorter-v2-03-build-duplicate-detection.md':958 'turbo/spec.md':179 'turbo/specs':143,149,174,215 'two':1202 'type':686,788 'ui':254,584,697,792 'understand':1502 'union':853,1541 'unit':62,566 'unreach':637 'unrel':611 'updat':537,545,1058 'use':33,76,116,131,156,165,181,227,779,908,1017,1177,1330,1448 'user':36,126,192,1011,1089,1409 'usual':477 'v2':939,950,1355,1361 'verif':1277 'vs':289 'whether':453 'wire':17,751 'within':298 'without':28,1316,1505 'work':64,251,252,297,568,667,670,740,880,1188,1504 'worthi':336 'would':601,1125 'write':99,1158,1171 'written':956 'yaml':11,1349 'yet':1120","prices":[{"id":"a189ebc5-b4d3-4e3c-b648-7633ebd97f18","listingId":"c9eb22ef-5151-4aa0-9021-e758819668ac","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:40.643Z"}],"sources":[{"listingId":"c9eb22ef-5151-4aa0-9021-e758819668ac","source":"github","sourceId":"tobihagemann/turbo/draft-shells","sourceUrl":"https://github.com/tobihagemann/turbo/tree/main/skills/draft-shells","isPrimary":false,"firstSeenAt":"2026-04-18T22:03:40.643Z","lastSeenAt":"2026-04-22T00:54:09.080Z"}],"details":{"listingId":"c9eb22ef-5151-4aa0-9021-e758819668ac","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"tobihagemann","slug":"draft-shells","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":"db18511231c5b01828638b0f27d9937fd7cb3652","skill_md_path":"skills/draft-shells/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/tobihagemann/turbo/tree/main/skills/draft-shells"},"layout":"multi","source":"github","category":"turbo","frontmatter":{"name":"draft-shells","description":"Decompose a specification file into shells with YAML frontmatter. Each shell captures the wiring invariants (Produces, Consumes, Covers) and high-level Implementation Steps without committing to file paths. Use when the user asks to \"draft shells\", \"create shells\", \"break spec into shells\", \"decompose spec into sessions\", \"draft shells from spec\", \"generate shells from spec\", or \"make shells from spec\"."},"skills_sh_url":"https://skills.sh/tobihagemann/turbo/draft-shells"},"updatedAt":"2026-04-22T00:54:09.080Z"}}