{"id":"e9c658a1-0df3-4162-871a-b33a9771418a","shortId":"fExrV3","kind":"skill","title":"Architecture Explainer","tagline":"Reads a codebase or system description and produces a clear, structured architecture overview with diagrams.","description":"# Architecture Explainer\n\n## What this skill does\n\nThis skill directs the agent to explore a codebase or system description and produce a clear, structured architecture overview. It maps out layers, major components, data flows, and external dependencies, then renders ASCII diagrams showing how the pieces connect. The result is a document a new engineer could read in 10 minutes and understand how the system works.\n\nUse this when onboarding new team members, preparing for an architecture review, creating documentation for a system you inherited, or clarifying your own mental model before a large refactor.\n\n## How to use\n\n### Claude Code / Cline\n\nCopy this file to `.agents/skills/architecture-explainer/SKILL.md` in your project root.\n\nThen ask:\n- *\"Use the Architecture Explainer skill to document this entire repo.\"*\n- *\"Explain the architecture of the `server/` directory using the Architecture Explainer skill.\"*\n- *\"I'll describe our system. Use the Architecture Explainer skill to turn it into a structured overview.\"*\n\n### Cursor\n\nAdd the instructions below to your `.cursorrules` or paste them into the Cursor AI pane before asking for the architecture overview.\n\n### Codex\n\nProvide a directory listing or paste key files and ask Codex to follow the instructions below to produce the architecture document.\n\n## The Prompt / Instructions for the Agent\n\nWhen asked to explain or document an architecture, follow these steps:\n\n### Step 1 — Explore the codebase\n\nStart by reading:\n1. The root directory listing\n2. `package.json`, `pyproject.toml`, `go.mod`, or the equivalent dependency manifest\n3. Entry point files (e.g., `main.ts`, `index.ts`, `app.py`, `cmd/main.go`)\n4. Top-level directory names and their `index` or `README` files if present\n5. Any existing architecture or design docs\n\nDo not read every file. Use the directory structure and entry points to infer the layering.\n\n### Step 2 — Identify the major components\n\nExtract:\n- **Layers**: presentation, business logic, data access, infrastructure\n- **Services or modules**: each significant unit of functionality\n- **External dependencies**: databases, caches, third-party APIs, message queues\n- **Entry points**: HTTP routes, CLI commands, event listeners, cron jobs\n- **Shared utilities**: auth, logging, config, error handling\n\n### Step 3 — Map the data flow\n\nFor the most important 2–3 user-facing operations, trace:\n- Where the request enters the system\n- Which layers or modules it passes through\n- What data is read or written and where\n- Where the response is assembled and returned\n\n### Step 4 — Produce the architecture document\n\nFormat the output as follows:\n\n```markdown\n# Architecture Overview — [Project Name]\n\n## System Summary\n[2–3 sentences. What does this system do? What are the key technical choices (language, framework, DB)?]\n\n## Layer Diagram\n\n[ASCII diagram showing the main layers top-to-bottom, e.g.:]\n\n┌─────────────────────────────────┐\n│         Client / Browser        │\n└────────────────┬────────────────┘\n                 │ HTTP / REST\n┌────────────────▼────────────────┐\n│        Express API Server       │\n│  routes/ → controllers/ → ...   │\n└──────┬─────────────┬────────────┘\n       │             │\n┌──────▼──────┐ ┌────▼────────────┐\n│  PostgreSQL  │ │  Redis Cache    │\n└─────────────┘ └─────────────────┘\n\n## Component Breakdown\n\n### [Component Name]\n- **Location**: `src/payments/`\n- **Responsibility**: [1–2 sentences]\n- **Depends on**: [List of other components or external services]\n- **Depended on by**: [Who calls this]\n\n[Repeat for each major component]\n\n## Key Data Flows\n\n### [Flow name, e.g., \"User places an order\"]\n1. Request arrives at `POST /api/orders`\n2. `OrderController` validates the request body\n3. `OrderService` runs business logic and calls `PaymentService`\n4. `PaymentService` calls Stripe API\n5. On success, `OrderRepository` writes to `orders` table\n6. Response returned to client\n\n[Repeat for 2–3 key flows]\n\n## External Dependencies\n\n| Dependency | Purpose | Where integrated |\n|------------|---------|-----------------|\n| PostgreSQL | Primary data store | `server/db/` |\n| Redis | Session cache | `server/cache/` |\n| Stripe | Payment processing | `server/services/payment.ts` |\n\n## What is NOT covered here\n[Note any parts of the system this document doesn't address, e.g., \"Worker queue jobs not documented\"]\n```\n\n### Step 5 — Validate your understanding\n\nAfter writing the document, re-read the entry point files and check that every major path through the system is accounted for. If something doesn't fit your model, revise the model — don't ignore the discrepancy.\n\n## Example\n\n**Input to Agent:**\n> \"Use the Architecture Explainer skill on this repo. Here's the directory tree:\n> ```\n> src/\n>   api/routes/\n>   api/controllers/\n>   services/\n>   db/repositories/\n>   workers/\n> client/\n>   pages/\n>   components/\n> ```\"\n\n**Output from Agent:**\n\n> # Architecture Overview — MyApp\n>\n> ## System Summary\n> MyApp is a full-stack web application built with Node.js/Express on the backend and React on the frontend. It uses PostgreSQL for persistence and background workers for async processing.\n>\n> ## Layer Diagram\n>\n> ```\n> ┌──────────────────────────┐\n> │   React Client (client/) │\n> └────────────┬─────────────┘\n>              │ HTTP/JSON\n> ┌────────────▼─────────────┐\n> │ Express API (src/api/)   │\n> │  routes/ → controllers/  │\n> └──────┬───────────────────┘\n>        │\n> ┌──────▼───────────────────┐\n> │ Services (src/services/) │\n> └──────┬───────────────────┘\n>        │\n> ┌──────▼───────────────────┐  ┌──────────────────┐\n> │ Repositories (src/db/)   │  │ Workers           │\n> └──────┬───────────────────┘  │ (src/workers/)    │\n>        │                      └──────────────────┘\n> ┌──────▼───────────────────┐\n> │       PostgreSQL         │\n> └──────────────────────────┘\n> ```\n>\n> ## Component Breakdown\n>\n> ### API Routes\n> - **Location**: `src/api/routes/`\n> - **Responsibility**: Maps HTTP methods and paths to controller functions\n> - **Depends on**: Controllers\n>\n> ### Services\n> - **Location**: `src/services/`\n> - **Responsibility**: Contains all business logic; orchestrates calls between repositories and external APIs\n> - **Depends on**: Repositories, external APIs\n> - **Depended on by**: Controllers, Workers\n\n## Notes\n\n- For very large repos, ask the agent to focus on one service or one top-level directory at a time.\n- If you have an existing architecture doc, paste it in and ask the agent to update it rather than writing from scratch.\n- ASCII diagrams can be copied into tools like Mermaid or draw.io for polish.","tags":["architecture","explainer","openagentskills","notysoty","agent-skills","claude","claude-code","claude-skills","cline","cursor","llm","llm-skills"],"capabilities":["skill","source-notysoty","skill-architecture-explainer","topic-agent-skills","topic-claude","topic-claude-code","topic-claude-skills","topic-cline","topic-cursor","topic-llm","topic-llm-skills","topic-skills"],"categories":["openagentskills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/Notysoty/openagentskills/architecture-explainer","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add Notysoty/openagentskills","source_repo":"https://github.com/Notysoty/openagentskills","install_from":"skills.sh"}},"qualityScore":"0.454","qualityRationale":"deterministic score 0.45 from registry signals: · indexed on github topic:agent-skills · 8 github stars · SKILL.md body (6,594 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-18T19:13:20.349Z","embedding":null,"createdAt":"2026-05-18T13:20:40.701Z","updatedAt":"2026-05-18T19:13:20.349Z","lastSeenAt":"2026-05-18T19:13:20.349Z","tsv":"'/api/orders':495 '/express':664 '1':229,236,457,490 '10':74 '2':241,297,355,408,458,496,530 '3':250,346,356,409,502,531 '4':259,391,510 '5':273,515,576 '6':523 'access':308 'account':601 'add':168 'address':568 'agent':28,216,621,646,752,780 'agents/skills/architecture-explainer/skill.md':121 'ai':181 'api':325,443,514,691,704,734,739 'api/controllers':637 'api/routes':636 'app.py':257 'applic':659 'architectur':1,14,18,41,92,130,140,147,157,187,209,224,276,394,402,624,647,772 'arriv':492 'ascii':56,427,789 'ask':127,184,199,218,750,778 'assembl':387 'async':682 'auth':340 'backend':667 'background':679 'bodi':501 'bottom':436 'breakdown':451,703 'browser':439 'built':660 'busi':305,505,726 'cach':321,449,547 'call':473,508,512,729 'check':592 'choic':421 'clarifi':102 'claud':114 'clear':12,39 'cli':332 'client':438,527,641,687,688 'cline':116 'cmd/main.go':258 'code':115 'codebas':5,32,232 'codex':189,200 'command':333 'compon':48,301,450,452,465,479,643,702 'config':342 'connect':62 'contain':724 'control':446,694,715,719,743 'copi':117,793 'could':71 'cover':556 'creat':94 'cron':336 'cursor':167,180 'cursorrul':174 'data':49,307,349,376,481,542 'databas':320 'db':424 'db/repositories':639 'depend':53,248,319,460,469,535,536,717,735,740 'describ':152 'descript':8,35 'design':278 'diagram':17,57,426,428,685,790 'direct':26 'directori':144,192,239,263,287,633,763 'discrep':617 'doc':279,773 'document':67,95,134,210,222,395,565,574,583 'doesn':566,605 'draw.io':799 'e.g':254,437,485,569 'engin':70 'enter':365 'entir':136 'entri':251,290,328,588 'equival':247 'error':343 'event':334 'everi':283,594 'exampl':618 'exist':275,771 'explain':2,19,131,138,148,158,220,625 'explor':30,230 'express':442,690 'extern':52,318,467,534,733,738 'extract':302 'face':359 'file':119,197,253,270,284,590 'fit':607 'flow':50,350,482,483,533 'focus':754 'follow':202,225,400 'format':396 'framework':423 'frontend':672 'full':656 'full-stack':655 'function':317,716 'go.mod':244 'handl':344 'http':330,440,710 'http/json':689 'identifi':298 'ignor':615 'import':354 'index':267 'index.ts':256 'infer':293 'infrastructur':309 'inherit':100 'input':619 'instruct':170,204,213 'integr':539 'job':337,572 'key':196,419,480,532 'languag':422 'larg':109,748 'layer':46,295,303,369,425,432,684 'level':262,762 'like':796 'list':193,240,462 'listen':335 'll':151 'locat':454,706,721 'log':341 'logic':306,506,727 'main':431 'main.ts':255 'major':47,300,478,595 'manifest':249 'map':44,347,709 'markdown':401 'member':88 'mental':105 'mermaid':797 'messag':326 'method':711 'minut':75 'model':106,609,612 'modul':312,371 'myapp':649,652 'name':264,405,453,484 'new':69,86 'node.js':663 'node.js/express':662 'note':558,745 'onboard':85 'one':756,759 'oper':360 'orchestr':728 'order':489,521 'ordercontrol':497 'orderrepositori':518 'orderservic':503 'output':398,644 'overview':15,42,166,188,403,648 'package.json':242 'page':642 'pane':182 'part':560 'parti':324 'pass':373 'past':176,195,774 'path':596,713 'payment':550 'paymentservic':509,511 'persist':677 'piec':61 'place':487 'point':252,291,329,589 'polish':801 'post':494 'postgresql':447,540,675,701 'prepar':89 'present':272,304 'primari':541 'process':551,683 'produc':10,37,207,392 'project':124,404 'prompt':212 'provid':190 'purpos':537 'pyproject.toml':243 'queue':327,571 'rather':784 're':585 're-read':584 'react':669,686 'read':3,72,235,282,378,586 'readm':269 'redi':448,545 'refactor':110 'render':55 'repeat':475,528 'repo':137,629,749 'repositori':697,731,737 'request':364,491,500 'respons':385,456,524,708,723 'rest':441 'result':64 'return':389,525 'review':93 'revis':610 'root':125,238 'rout':331,445,693,705 'run':504 'scratch':788 'sentenc':410,459 'server':143,444 'server/cache':548 'server/db':544 'server/services/payment.ts':552 'servic':310,468,638,695,720,757 'session':546 'share':338 'show':58,429 'signific':314 'skill':22,25,132,149,159,626 'skill-architecture-explainer' 'someth':604 'source-notysoty' 'src':635 'src/api':692 'src/api/routes':707 'src/db':698 'src/payments':455 'src/services':696,722 'src/workers':700 'stack':657 'start':233 'step':227,228,296,345,390,575 'store':543 'stripe':513,549 'structur':13,40,165,288 'success':517 'summari':407,651 'system':7,34,80,98,154,367,406,414,563,599,650 'tabl':522 'team':87 'technic':420 'third':323 'third-parti':322 'time':766 'tool':795 'top':261,434,761 'top-level':260,760 'top-to-bottom':433 'topic-agent-skills' 'topic-claude' 'topic-claude-code' 'topic-claude-skills' 'topic-cline' 'topic-cursor' 'topic-llm' 'topic-llm-skills' 'topic-skills' 'trace':361 'tree':634 'turn':161 'understand':77,579 'unit':315 'updat':782 'use':82,113,128,145,155,285,622,674 'user':358,486 'user-fac':357 'util':339 'valid':498,577 'web':658 'work':81 'worker':570,640,680,699,744 'write':519,581,786 'written':380","prices":[{"id":"6be9afb2-05f4-4437-9803-4296bd658375","listingId":"e9c658a1-0df3-4162-871a-b33a9771418a","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"Notysoty","category":"openagentskills","install_from":"skills.sh"},"createdAt":"2026-05-18T13:20:40.701Z"}],"sources":[{"listingId":"e9c658a1-0df3-4162-871a-b33a9771418a","source":"github","sourceId":"Notysoty/openagentskills/architecture-explainer","sourceUrl":"https://github.com/Notysoty/openagentskills/tree/main/skills/architecture-explainer","isPrimary":false,"firstSeenAt":"2026-05-18T13:20:40.701Z","lastSeenAt":"2026-05-18T19:13:20.349Z"}],"details":{"listingId":"e9c658a1-0df3-4162-871a-b33a9771418a","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"Notysoty","slug":"architecture-explainer","github":{"repo":"Notysoty/openagentskills","stars":8,"topics":["agent-skills","claude","claude-code","claude-skills","cline","cursor","llm","llm-skills","skills"],"license":"mit","html_url":"https://github.com/Notysoty/openagentskills","pushed_at":"2026-03-28T06:50:19Z","description":"A  community-driven library of reusable AI agent skills for Claude Code, Cursor, Codex, Cline, and more.","skill_md_sha":"8c4f18f1c7b001fa760feb1c0ee5dbe8196c5e3a","skill_md_path":"skills/architecture-explainer/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/Notysoty/openagentskills/tree/main/skills/architecture-explainer"},"layout":"multi","source":"github","category":"openagentskills","frontmatter":{"name":"Architecture Explainer","description":"Reads a codebase or system description and produces a clear, structured architecture overview with diagrams."},"skills_sh_url":"https://skills.sh/Notysoty/openagentskills/architecture-explainer"},"updatedAt":"2026-05-18T19:13:20.349Z"}}