{"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\nLaunch all Agent tool calls in parallel (`model: \"opus\"`, do not set `run_in_background`). Each agent receives the scoped file manifest and its exploration brief. Batch across multiple messages if the total exceeds what can be launched at once.\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.590","qualityRationale":"deterministic score 0.59 from registry signals: · indexed on github topic:agent-skills · 280 github stars · SKILL.md body (5,243 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:10.421Z","embedding":null,"createdAt":"2026-04-18T22:03:51.900Z","updatedAt":"2026-04-22T00:54:10.421Z","lastSeenAt":"2026-04-22T00:54:10.421Z","tsv":"'-5':509,552 '/frontend-design':615 '1':78,95,286,483,612 '2':80,191,316,488,621 '3':84,338,473,502,508,551,629 '4':90,365,517,598 '5':392,525 '6':416 '7':439 'abstract':367,436,576 'across':12,47,222 'adapt':256 'agent':83,175,180,194,197,211,238,242,254,461,481,486,687,695,705 'analysi':62 'analysis-on':61 'angl':712 'anim':669 'api':21,343,426,574 'approach':410,450 'appropri':154 'architectur':5,41,379,498,563,647 'area':364 'argument':98 'askuserquest':109 'aspect':14,49 'background':209 'base':185,305,308 'batch':221 'beyond':183,641 'boundari':415,430 'brief':220,252,285,505 'build':145,148,158,313,320,327 'call':199 'captur':511 'card':652 'charact':516 'choic':564 'ci/cd':453 'class':373 'cli':350 'code':391,667,724 'codebas':3,17,39,52,114,545 'collaps':657 'command':351 'commit':728 'compat':336 'complet':482 'complex':260 'comprehens':32 'concret':274 'confirm':111 'connect':494,593 'constraint':334 'contain':634 'content':628 'contradict':519 'convent':295 'convert':602 'core':366,575 'coupl':438 'coverag':449 'creat':72 'cross':491,585 'cross-cut':490,584 'cut':492,586 'data':23,393,399,414,577 'databas':427 'date':547 'deep':4,40 'deeper':258 'defin':565 'depend':25,418,434,580,640 'deriveddata':149 'describ':444 'design':376,619 'determin':128 'differ':13,48,711 'dimens':235,240,283,496,523,658,704 'direct':103 'directori':121,141,168,279,290,315,662 'discov':189 'dist':144 'document':33 'endpoint':353 'enter':400 'entir':113 'entranc':668 'entri':339,571 'essenti':515 'etc':385 'event':354 'everyth':116 'exceed':228 'exclud':137 'execut':506,534,549,650 'exit':404 'expect':714 'explor':182,219,251,255,284 'export':356 'extern':417,433,579,639 'fail':688 'failur':699 'fan':8,43 'featur':304 'feature-bas':303 'file':123,132,160,215,247,277,297,541,637,660,726 'find':29,55,271,344,464,691 'flow':24,394,578 'font':643 'framework':324,448 'friend':675 'full':626 'function':359 'gap':456 'generat':87,91,138,311,476,599 'generic':282 'glob':129 'go':257 'googl':642 'group':162 'handler':355 'high':265 'high-level':264 'hover':671 'html':92,600,610 'http':352 'hybrid':309 'identifi':299,322,370,407,489,594 'independ':707 'infrastructur':443 'inlin':666 'inspect':11,46,82,115,193 'integr':420 'interact':609 'interfac':374 'invok':349 'key':371 'languag':323 'launch':81,192,195,232,236 'layer':307,412 'layer-bas':306 'layout':291,681 'level':166,266 'load':618 'main':358 'manag':326,409 'manifest':161,170,216,248 'map':2,38,289,360,421,546 'map-codebas':1 'markdown':88,467,477,544,604 'may':181 'media':678 'messag':224 'mobil':683 'model':202 'modifi':722 'modul':143,292,357 'multipl':223 'mvc':381 'name':294 'navig':654 'node':142 'note':310,332,378,431,455,697 'observ':587,709 'off':501,591 'one':237 'oper':706 'opus':203 'organ':293,301,452,561 'other':153 'otherwis':107 'output':314,532 'overlap':521,708,719 'packag':325 'page':611 'parallel':10,45,201 'parti':424 'path':100,118 'pattern':22,124,369,377,380,459 'per':239 'persist':402 'phase':77 'pipelin':384,454 'plugin':382 'point':179,340,572 'present':645 'principl':302,620 'print':674,679 'print-friend':673 'proceed':689 'project':157,287,567 'prompt':244 'provid':120,245 'public':342,362 'pycach':147 'qualiti':442,583 'question':106 'rather':280 'read':484,622 'receiv':212 'refer':275,663 'remain':694 'report':6,42,89,93,478,487,524,530,542,601,605,627,648,702 'requir':331 'resolv':518,718 'respons':680 'role':298 'rule':684 'run':207,613 'runtim':330 'scope':79,96,112,126,136,214,548 'section':469,656,659 'select':135 'self':633 'self-contain':632 'sentenc':510,553 'servic':425 'set':206 'shape':389 'share':172 'singl':636 'skill':616 'skill-map-codebase' 'skip':104 'sourc':131,167,723 'source-tobihagemann' 'specif':117,276 'specifi':99 'stack':20,318,570 'stage':725 'start':68,178 'state':396,408,672 'stay':263 'step':94,190,472,597,717 'sticki':653 'storag':411 'straightforward':270 'strategi':447 'structur':18,288,466,568 'style':608,665,676 'subsect':471 'summari':507,535,550,651 'surfac':363 'synthes':28,53,85,474 'synthesi':596,716 'system':321,347,383,406,429,513,556 'target':150,337 'task':64,74 'taskcreat':70 'tech':19,317,569 'templat':531,543 'test':26,440,446,451,581 'text':537 'theme':493,588 'thing':268 'third':423 'third-parti':422 'tool':198,328 'top':165 'top-level':164 'topic-agent-skills' 'topic-claude-code' 'topic-claude-skills' 'topic-developer-tools' 'topic-skills' 'total':227 'tox':151 'trace':397 'track':65 'trade':500,590 'trade-off':499,589 'transform':401 'turbo/codebase-map':37 'turbo/codebase-map.html':60,635 'turbo/codebase-map.md':35,58,527,623 'type':372 'unusu':458 'use':69,101,108,528 'user':119 'vendor':140,146 'version':333 'via':677 'warrant':261 'write':57,462,503,526,539,630","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-04-22T00:54:10.421Z"}],"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":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":"48e10df839bd2622a976fed33c89117fd842f901","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-04-22T00:54:10.421Z"}}