{"id":"5a81d541-4af6-4ba9-91e0-de5f936ae0e4","shortId":"FR4vdb","kind":"skill","title":"map-codebase","tagline":"Deep architecture report that fans out parallel inspections across different aspects of the codebase (structure, tech stack, APIs, patterns, data flow, dependencies, testing) and synthesizes findings into a comprehensive document at .turbo/codebase-map.md and .turbo/codebase-map.","description":"# Map Codebase\n\nDeep architecture report. Fans out parallel inspections across different aspects of the codebase, synthesizes their findings, and writes `.turbo/codebase-map.md` and `.turbo/codebase-map.html`. Analysis-only.\n\n## Task Tracking\n\nAt the start, use `TaskCreate` to create a task for each phase:\n\n1. Scope\n2. Launch inspection agents\n3. Synthesize and generate markdown report\n4. Generate HTML report\n\n## Step 1: Scope\n\nIf `$ARGUMENTS` specifies paths, use those directly (skip the question).\n\nOtherwise, use `AskUserQuestion` to confirm scope:\n\n- **Entire codebase** — inspect everything\n- **Specific paths** — user provides directories or file patterns\n\nOnce scope is determined, glob for source files in the selected scope. Exclude generated and vendored directories (`node_modules/`, `dist/`, `build/`, `vendor/`, `__pycache__/`, `.build/`, `DerivedData/`, `target/`, `.tox/`, and others appropriate to the project).\n\nBuild a file manifest grouped by top-level source directory. This manifest is shared with all agents as a starting point. Agents may explore beyond it based on what they discover.\n\n## Step 2: Launch Inspection Agents\n\nUse the Agent tool to launch all 7 agents below in a single assistant message so they run concurrently. Each Agent call uses `model: \"opus\"` and does not set `run_in_background`. Each agent receives the scoped file manifest and its exploration brief.\n\n### Dimensions\n\nLaunch one agent per dimension. Each agent's prompt provides the file manifest and the exploration brief below. Agents explore adaptively: go deeper where complexity warrants it, stay high-level where things are straightforward. Findings should be concrete (reference specific files and directories) rather than generic.\n\n| # | Dimension | Exploration Brief |\n|---|---|---|\n| 1 | Project Structure | Map directory layout, module organization, naming conventions, and file roles. Identify the organizing principle (feature-based, layer-based, hybrid). Note generated or build output directories. |\n| 2 | Tech Stack and Build System | Identify languages, frameworks, package managers, build tools, and runtime requirements. Note version constraints and compatibility targets. |\n| 3 | Entry Points and Public API | Find how the system is invoked: CLI commands, HTTP endpoints, event handlers, exported modules, main functions. Map the public surface area. |\n| 4 | Core Abstractions and Patterns | Identify key types, classes, interfaces, and design patterns. Note architectural patterns (MVC, plugin system, pipeline, etc.) and how they shape the code. |\n| 5 | Data Flow and State | Trace how data enters, transforms, persists, and exits the system. Identify state management approaches, storage layers, and data boundaries. |\n| 6 | External Dependencies and Integrations | Map third-party services, APIs, databases, and system boundaries. Note how external dependencies are abstracted or coupled. |\n| 7 | Testing and Quality Infrastructure | Describe the test strategy: frameworks, coverage approach, test organization, CI/CD pipeline. Note gaps or unusual patterns. |\n\nEach agent writes its findings as structured markdown with sections and subsections.\n\n## Step 3: Synthesize and Generate Markdown Report\n\nAfter all agents complete:\n\n1. Read all agent reports.\n2. Identify cross-cutting themes, connections between dimensions, and architectural trade-offs.\n3. Write a brief executive summary (3-5 sentences) capturing the system's essential character.\n4. Resolve contradictions or overlaps between dimension reports.\n5. Write `.turbo/codebase-map.md` using the report template. Output the executive summary as text before writing the file.\n\n### Report Template\n\n```markdown\n# Codebase Map\n\n**Date:** <date>\n**Scope:** <what was inspected>\n\n## Executive Summary\n\n<3-5 sentences: what the system is, how it's organized, what architectural choices define it>\n\n## Project Structure\n\n<from dimension 1>\n\n## Tech Stack\n\n<from dimension 2>\n\n## Entry Points and API\n\n<from dimension 3>\n\n## Core Abstractions\n\n<from dimension 4>\n\n## Data Flow\n\n<from dimension 5>\n\n## External Dependencies\n\n<from dimension 6>\n\n## Testing and Quality\n\n<from dimension 7>\n\n## Cross-Cutting Observations\n\n<themes, trade-offs, and connections identified during synthesis>\n```\n\n## Step 4: Generate HTML Report\n\nConvert the markdown report into a styled, interactive HTML page.\n\n1. Run the `/frontend-design` skill to load design principles.\n2. Read `.turbo/codebase-map.md` for the full report content.\n3. Write a self-contained `.turbo/codebase-map.html` (single file, no external dependencies beyond Google Fonts) that presents the architecture report with:\n   - Executive summary card\n   - Sticky navigation between sections\n   - Collapsible dimension sections\n   - File and directory references as styled inline code\n   - Entrance animations and hover states\n   - Print-friendly styles via `@media print`\n   - Responsive layout for mobile\n\n## Rules\n\n- If any agent fails, proceed with findings from the remaining agents and note the failure in the report.\n- Each dimension agent operates independently. Overlapping observations from different angles are expected. The synthesis step resolves overlaps.\n- Does not modify source code, stage files, or commit.","tags":["map","codebase","turbo","tobihagemann","agent-skills","claude-code","claude-skills","developer-tools","skills"],"capabilities":["skill","source-tobihagemann","skill-map-codebase","topic-agent-skills","topic-claude-code","topic-claude-skills","topic-developer-tools","topic-skills"],"categories":["turbo"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/tobihagemann/turbo/map-codebase","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.597","qualityRationale":"deterministic score 0.60 from registry signals: · indexed on github topic:agent-skills · 295 github stars · SKILL.md body (5,249 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-08T06:54:09.555Z","embedding":null,"createdAt":"2026-04-18T22:03:51.900Z","updatedAt":"2026-05-08T06:54:09.555Z","lastSeenAt":"2026-05-08T06:54:09.555Z","tsv":"'-5':512,555 '/frontend-design':618 '1':78,95,289,486,615 '2':80,191,319,491,624 '3':84,341,476,505,511,554,632 '4':90,368,520,601 '5':395,528 '6':419 '7':202,442 'abstract':370,439,579 'across':12,47 'adapt':259 'agent':83,175,180,194,197,203,215,228,241,245,257,464,484,489,690,698,708 'analysi':62 'analysis-on':61 'angl':715 'anim':672 'api':21,346,429,577 'approach':413,453 'appropri':154 'architectur':5,41,382,501,566,650 'area':367 'argument':98 'askuserquest':109 'aspect':14,49 'assist':208 'background':226 'base':185,308,311 'beyond':183,644 'boundari':418,433 'brief':237,255,288,508 'build':145,148,158,316,323,330 'call':216 'captur':514 'card':655 'charact':519 'choic':567 'ci/cd':456 'class':376 'cli':353 'code':394,670,727 'codebas':3,17,39,52,114,548 'collaps':660 'command':354 'commit':731 'compat':339 'complet':485 'complex':263 'comprehens':32 'concret':277 'concurr':213 'confirm':111 'connect':497,596 'constraint':337 'contain':637 'content':631 'contradict':522 'convent':298 'convert':605 'core':369,578 'coupl':441 'coverag':452 'creat':72 'cross':494,588 'cross-cut':493,587 'cut':495,589 'data':23,396,402,417,580 'databas':430 'date':550 'deep':4,40 'deeper':261 'defin':568 'depend':25,421,437,583,643 'deriveddata':149 'describ':447 'design':379,622 'determin':128 'differ':13,48,714 'dimens':238,243,286,499,526,661,707 'direct':103 'directori':121,141,168,282,293,318,665 'discov':189 'dist':144 'document':33 'endpoint':356 'enter':403 'entir':113 'entranc':671 'entri':342,574 'essenti':518 'etc':388 'event':357 'everyth':116 'exclud':137 'execut':509,537,552,653 'exit':407 'expect':717 'explor':182,236,254,258,287 'export':359 'extern':420,436,582,642 'fail':691 'failur':702 'fan':8,43 'featur':307 'feature-bas':306 'file':123,132,160,232,250,280,300,544,640,663,729 'find':29,55,274,347,467,694 'flow':24,397,581 'font':646 'framework':327,451 'friend':678 'full':629 'function':362 'gap':459 'generat':87,91,138,314,479,602 'generic':285 'glob':129 'go':260 'googl':645 'group':162 'handler':358 'high':268 'high-level':267 'hover':674 'html':92,603,613 'http':355 'hybrid':312 'identifi':302,325,373,410,492,597 'independ':710 'infrastructur':446 'inlin':669 'inspect':11,46,82,115,193 'integr':423 'interact':612 'interfac':377 'invok':352 'key':374 'languag':326 'launch':81,192,200,239 'layer':310,415 'layer-bas':309 'layout':294,684 'level':166,269 'load':621 'main':361 'manag':329,412 'manifest':161,170,233,251 'map':2,38,292,363,424,549 'map-codebas':1 'markdown':88,470,480,547,607 'may':181 'media':681 'messag':209 'mobil':686 'model':218 'modifi':725 'modul':143,295,360 'mvc':384 'name':297 'navig':657 'node':142 'note':313,335,381,434,458,700 'observ':590,712 'off':504,594 'one':240 'oper':709 'opus':219 'organ':296,304,455,564 'other':153 'otherwis':107 'output':317,535 'overlap':524,711,722 'packag':328 'page':614 'parallel':10,45 'parti':427 'path':100,118 'pattern':22,124,372,380,383,462 'per':242 'persist':405 'phase':77 'pipelin':387,457 'plugin':385 'point':179,343,575 'present':648 'principl':305,623 'print':677,682 'print-friend':676 'proceed':692 'project':157,290,570 'prompt':247 'provid':120,248 'public':345,365 'pycach':147 'qualiti':445,586 'question':106 'rather':283 'read':487,625 'receiv':229 'refer':278,666 'remain':697 'report':6,42,89,93,481,490,527,533,545,604,608,630,651,705 'requir':334 'resolv':521,721 'respons':683 'role':301 'rule':687 'run':212,224,616 'runtim':333 'scope':79,96,112,126,136,231,551 'section':472,659,662 'select':135 'self':636 'self-contain':635 'sentenc':513,556 'servic':428 'set':223 'shape':392 'share':172 'singl':207,639 'skill':619 'skill-map-codebase' 'skip':104 'sourc':131,167,726 'source-tobihagemann' 'specif':117,279 'specifi':99 'stack':20,321,573 'stage':728 'start':68,178 'state':399,411,675 'stay':266 'step':94,190,475,600,720 'sticki':656 'storag':414 'straightforward':273 'strategi':450 'structur':18,291,469,571 'style':611,668,679 'subsect':474 'summari':510,538,553,654 'surfac':366 'synthes':28,53,85,477 'synthesi':599,719 'system':324,350,386,409,432,516,559 'target':150,340 'task':64,74 'taskcreat':70 'tech':19,320,572 'templat':534,546 'test':26,443,449,454,584 'text':540 'theme':496,591 'thing':271 'third':426 'third-parti':425 'tool':198,331 'top':165 'top-level':164 'topic-agent-skills' 'topic-claude-code' 'topic-claude-skills' 'topic-developer-tools' 'topic-skills' 'tox':151 'trace':400 'track':65 'trade':503,593 'trade-off':502,592 'transform':404 'turbo/codebase-map':37 'turbo/codebase-map.html':60,638 'turbo/codebase-map.md':35,58,530,626 'type':375 'unusu':461 'use':69,101,108,195,217,531 'user':119 'vendor':140,146 'version':336 'via':680 'warrant':264 'write':57,465,506,529,542,633","prices":[{"id":"2e761e51-f8f3-45ef-9807-9917b8a571fb","listingId":"5a81d541-4af6-4ba9-91e0-de5f936ae0e4","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:51.900Z"}],"sources":[{"listingId":"5a81d541-4af6-4ba9-91e0-de5f936ae0e4","source":"github","sourceId":"tobihagemann/turbo/map-codebase","sourceUrl":"https://github.com/tobihagemann/turbo/tree/main/skills/map-codebase","isPrimary":false,"firstSeenAt":"2026-04-18T22:03:51.900Z","lastSeenAt":"2026-05-08T06:54:09.555Z"}],"details":{"listingId":"5a81d541-4af6-4ba9-91e0-de5f936ae0e4","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"tobihagemann","slug":"map-codebase","github":{"repo":"tobihagemann/turbo","stars":295,"topics":["agent-skills","claude-code","claude-skills","developer-tools","skills"],"license":"mit","html_url":"https://github.com/tobihagemann/turbo","pushed_at":"2026-05-01T15:45:15Z","description":"A composable dev process for Claude Code, packaged as modular skills.","skill_md_sha":"278168375f9c9a01effa0d96f24f4931639d4f6e","skill_md_path":"skills/map-codebase/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/tobihagemann/turbo/tree/main/skills/map-codebase"},"layout":"multi","source":"github","category":"turbo","frontmatter":{"name":"map-codebase","description":"Deep architecture report that fans out parallel inspections across different aspects of the codebase (structure, tech stack, APIs, patterns, data flow, dependencies, testing) and synthesizes findings into a comprehensive document at .turbo/codebase-map.md and .turbo/codebase-map.html. Use when the user asks to \"map the codebase\", \"map codebase\", \"architecture report\", \"codebase overview\", \"architecture overview\", \"what am I looking at\", or \"explain this codebase\"."},"skills_sh_url":"https://skills.sh/tobihagemann/turbo/map-codebase"},"updatedAt":"2026-05-08T06:54:09.555Z"}}