{"id":"f5009170-7cec-410d-9aa3-cc2054cd3760","shortId":"Cy5YqX","kind":"skill","title":"explain","tagline":"Explain what a piece of code does — a specific file, class, or method in close detail, or a user-facing flow as a concise system overview. What it does and why, not whether it's good.","description":"## Behavior\n\nExplain `$ARGUMENTS`. Do the research and deliver the explanation in one pass.\n\nDetermine the mode from the argument:\n\n- **If the argument is a file path, class name, or method** — this is a **code explanation**. Follow the Code Explanation section.\n- **If the argument is a user action, feature, or flow description** (e.g. \"password reset\", \"checkout\", \"authentication\") — this is a **flow explanation**. Follow the Flow Explanation section.\n\n---\n\n## Code Explanation\n\nStart by checking the git history for the file: `git log --oneline -15 <file>` and `git log -1 -p <file>` for the most recent change. Commit messages often reveal the \"why\" that the code itself doesn't — a bug that was fixed, a refactor that simplified something, a workaround for an external constraint. Note anything that reframes the code before diving into it.\n\nThen read the code carefully and explain in this order:\n\n### 1. What it does — in one paragraph\n\nPlain English. No jargon, no code. Describe what this code accomplishes from the outside — what goes in, what comes out, what changes as a result. Write it the way you'd explain it to the client who asked for the feature.\n\n### 2. How it does it — walking through the logic\n\nNarrate the code path in plain English, step by step. For each meaningful chunk:\n\n- What is this step doing?\n- Why is it doing it here, in this order?\n- What would break if it wasn't here?\n\nDon't narrate every line — skip the obvious. Focus on the parts that require interpretation.\n\n### 3. Patterns and conventions in use\n\nName the Rails, Ruby, or design patterns this code is using — and why they appear here. Examples:\n\n- \"This is a service object following the thoughtbot pattern — one public `call` method, one responsibility\"\n- \"This is using `delegate` to avoid Law of Demeter violations\"\n- \"This callback is doing what's normally done in a service object — worth noting\"\n- \"This is a query object extracting complex AR logic out of the model\"\n\nIf the code is using a pattern poorly or unexpectedly, name that too — neutrally. This isn't a review, but understanding requires knowing when something is off-label.\n\n### 4. What to watch out for\n\nAny non-obvious behaviour, implicit dependencies, or things that would surprise someone maintaining this code. Not a critique — just \"here's what you'd need to know to work safely in this area.\"\n\n---\n\n## Flow Explanation\n\nStart with the Rails router. Locate the route(s) that correspond to the described flow. From each entry point, trace the execution path through the codebase — controllers, service objects, models, callbacks, jobs, mailers. Follow both success and failure paths.\n\nThen deliver the explanation in two parts: a **diagram** and a **summary**.\n\n### 1. Diagram\n\nRender a concise visual flowchart of the system using box-drawing characters. The diagram should show:\n\n- **States and transitions** — the lifecycle, not the method calls\n- **Decision points** — where the flow branches\n- **Key actions** — what happens at each step, described in plain English\n- **Terminal states** — where the flow ends\n\n**Conventions:**\n\n- Box-drawing characters for structure: `┌─┐`, `│`, `├──`, `└──`, `▼`, `◄`\n- Decision points as plain text with branches: `YES` / `NO`\n- Actions as concise descriptions, not method signatures\n- Indent sub-steps under their parent action\n\nThe goal is to outline the system concisely — show how it behaves, not how the code is structured. A reader should be able to understand the full lifecycle from the diagram alone.\n\nSee the example in `example.md` for the expected style and level of detail.\n\n### 2. Summary\n\nAfter the diagram, add three sections in plain English:\n\n**Entry points** — every way this flow can be triggered. For each, one sentence describing what triggers it and what it does.\n\n**Branching logic** — the conditions that shape the flow. Feature flags, state checks, validations, guard clauses — anything that determines which path is taken.\n\n**Side effects** — everything with consequences outside the immediate flow. Jobs, mailers, external API calls, broadcasts, cache writes, state transitions. The things you'd need to know about before touching this code.\n\n---\n\n## Tone\n\nClear and direct. You're translating, not teaching and not judging. The goal is that they finish with a working mental model of what this code does and how to navigate it. Skip all hedging — if something is unclear in the code itself, say so plainly.","tags":["explain","rails","consultant","thoughtbot","agent-skills","claude-code-consulting","claude-code-plugin","claude-code-rails","claude-code-skill","claude-code-skills","claude-skills"],"capabilities":["skill","source-thoughtbot","skill-explain","topic-agent-skills","topic-claude-code-consulting","topic-claude-code-plugin","topic-claude-code-rails","topic-claude-code-skill","topic-claude-code-skills","topic-claude-skills"],"categories":["rails-consultant"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/thoughtbot/rails-consultant/explain","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add thoughtbot/rails-consultant","source_repo":"https://github.com/thoughtbot/rails-consultant","install_from":"skills.sh"}},"qualityScore":"0.454","qualityRationale":"deterministic score 0.45 from registry signals: · indexed on github topic:agent-skills · 9 github stars · SKILL.md body (4,448 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:08:42.434Z","embedding":null,"createdAt":"2026-05-18T13:14:14.830Z","updatedAt":"2026-05-18T19:08:42.434Z","lastSeenAt":"2026-05-18T19:08:42.434Z","tsv":"'-1':123 '-15':119 '1':178,483 '2':226,610 '3':286 '4':390 'abl':587 'accomplish':195 'action':85,518,550,564 'add':615 'alon':596 'anyth':159,657 'api':676 'appear':306 'ar':355 'area':429 'argument':41,57,60,81 'ask':222 'authent':94 'avoid':329 'behav':576 'behavior':39 'behaviour':400 'box':495,536 'box-draw':494,535 'branch':516,547,642 'break':265 'broadcast':678 'bug':143 'cach':679 'call':320,510,677 'callback':335,462 'care':172 'chang':129,206 'charact':497,538 'check':109,653 'checkout':93 'chunk':248 'class':12,65 'claus':656 'clear':696 'client':220 'close':16 'code':7,72,76,105,138,163,171,190,194,237,300,363,411,580,694,721,737 'codebas':457 'come':203 'commit':130 'complex':354 'concis':26,487,552,572 'condit':645 'consequ':668 'constraint':157 'control':458 'convent':289,534 'correspond':442 'critiqu':414 'd':215,420,686 'decis':511,541 'deleg':327 'deliv':46,472 'demet':332 'depend':402 'describ':191,445,524,634 'descript':89,553 'design':297 'detail':17,609 'determin':52,659 'diagram':479,484,499,595,614 'direct':698 'dive':165 'doesn':140 'done':341 'draw':496,537 'e.g':90 'effect':665 'end':533 'english':186,241,527,620 'entri':449,621 'everi':274,623 'everyth':666 'exampl':308,599 'example.md':601 'execut':453 'expect':604 'explain':1,2,40,174,216 'explan':48,73,77,99,103,106,431,474 'extern':156,675 'extract':353 'face':22 'failur':469 'featur':86,225,650 'file':11,63,115 'finish':712 'fix':146 'flag':651 'flow':23,88,98,102,430,446,515,532,626,649,672 'flowchart':489 'focus':279 'follow':74,100,314,465 'full':591 'git':111,116,121 'goal':566,708 'goe':200 'good':38 'guard':655 'happen':520 'hedg':730 'histori':112 'immedi':671 'implicit':401 'indent':557 'interpret':285 'isn':376 'jargon':188 'job':463,673 'judg':706 'key':517 'know':383,423,689 'label':389 'law':330 'level':607 'lifecycl':506,592 'line':275 'locat':437 'log':117,122 'logic':234,356,643 'mailer':464,674 'maintain':409 'meaning':247 'mental':716 'messag':131 'method':14,68,321,509,555 'mode':54 'model':360,461,717 'name':66,292,371 'narrat':235,273 'navig':726 'need':421,687 'neutral':374 'non':398 'non-obvi':397 'normal':340 'note':158,347 'object':313,345,352,460 'obvious':278,399 'off-label':387 'often':132 'one':50,183,318,322,632 'onelin':118 'order':177,262 'outlin':569 'outsid':198,669 'overview':28 'p':124 'paragraph':184 'parent':563 'part':282,477 'pass':51 'password':91 'path':64,238,454,470,661 'pattern':287,298,317,367 'piec':5 'plain':185,240,526,544,619,741 'point':450,512,542,622 'poor':368 'public':319 'queri':351 'rail':294,435 're':700 'read':169 'reader':584 'recent':128 'refactor':148 'refram':161 'render':485 'requir':284,382 'research':44 'reset':92 'respons':323 'result':209 'reveal':133 'review':379 'rout':439 'router':436 'rubi':295 'safe':426 'say':739 'section':78,104,617 'see':597 'sentenc':633 'servic':312,344,459 'shape':647 'show':501,573 'side':664 'signatur':556 'simplifi':150 'skill' 'skill-explain' 'skip':276,728 'someon':408 'someth':151,385,732 'source-thoughtbot' 'specif':10 'start':107,432 'state':502,529,652,681 'step':242,244,252,523,560 'structur':540,582 'style':605 'sub':559 'sub-step':558 'success':467 'summari':482,611 'surpris':407 'system':27,492,571 'taken':663 'teach':703 'termin':528 'text':545 'thing':404,684 'thoughtbot':316 'three':616 'tone':695 'topic-agent-skills' 'topic-claude-code-consulting' 'topic-claude-code-plugin' 'topic-claude-code-rails' 'topic-claude-code-skill' 'topic-claude-code-skills' 'topic-claude-skills' 'touch':692 'trace':451 'transit':504,682 'translat':701 'trigger':629,636 'two':476 'unclear':734 'understand':381,589 'unexpect':370 'use':291,302,326,365,493 'user':21,84 'user-fac':20 'valid':654 'violat':333 'visual':488 'walk':231 'wasn':268 'watch':393 'way':213,624 'whether':35 'work':425,715 'workaround':153 'worth':346 'would':264,406 'write':210,680 'yes':548","prices":[{"id":"088bc965-85fe-4949-b760-1a098338a9fa","listingId":"f5009170-7cec-410d-9aa3-cc2054cd3760","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"thoughtbot","category":"rails-consultant","install_from":"skills.sh"},"createdAt":"2026-05-18T13:14:14.830Z"}],"sources":[{"listingId":"f5009170-7cec-410d-9aa3-cc2054cd3760","source":"github","sourceId":"thoughtbot/rails-consultant/explain","sourceUrl":"https://github.com/thoughtbot/rails-consultant/tree/main/skills/explain","isPrimary":false,"firstSeenAt":"2026-05-18T13:14:14.830Z","lastSeenAt":"2026-05-18T19:08:42.434Z"}],"details":{"listingId":"f5009170-7cec-410d-9aa3-cc2054cd3760","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"thoughtbot","slug":"explain","github":{"repo":"thoughtbot/rails-consultant","stars":9,"topics":["agent-skills","claude-code-consulting","claude-code-plugin","claude-code-rails","claude-code-skill","claude-code-skills","claude-skills"],"license":"mit","html_url":"https://github.com/thoughtbot/rails-consultant","pushed_at":"2026-03-27T16:24:47Z","description":"A collection of skills for Rails development and consulting with an emphasis on learning, communication, and client success. ","skill_md_sha":"3fe2cd5a96008f27fadcd6521a2566a153242544","skill_md_path":"skills/explain/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/thoughtbot/rails-consultant/tree/main/skills/explain"},"layout":"multi","source":"github","category":"rails-consultant","frontmatter":{"name":"explain","description":"Explain what a piece of code does — a specific file, class, or method in close detail, or a user-facing flow as a concise system overview. What it does and why, not whether it's good."},"skills_sh_url":"https://skills.sh/thoughtbot/rails-consultant/explain"},"updatedAt":"2026-05-18T19:08:42.434Z"}}