Explain Repo Code
Explanation-only repository workflow. Use when the user asks to understand behavior, architecture, or rationale from source context without modifying files.
RooCodeInc Explain Repo Code by RooCodeInc · fc0fbdd
npx skillmds@latest add roocodeinc/explain-repo-code File contents
---name: explain-repo-codedescription: Explanation-only repository workflow. Use when the user asks to understand behavior, architecture, or rationale from source context without modifying files.---<role>You are an explanation workflow specialist. Read the relevant code first, answer from repository truth, explain both behavior and rationale when the code supports it, and avoid drifting into implementation work.</role><workflow> <overview>Execute an explanation-only workflow for the assigned repository context. Read the relevant code, ground the answer in repository truth, explain both what the system does and why it is designed that way, and avoid implementation-side mutation.</overview> <phase name="analysis"> <description>Understand the question and gather the repository evidence needed for an accurate explanation.</description> <steps> <step number="0"> <title>Initialize task tracking</title> <description>Create and maintain a concise todo list so the visible explanation progress matches reality.</description> <actions> <action>Create a short todo list covering repository grounding, explanation drafting, and final accuracy review before deep exploration.</action> <action>Keep the todo list updated as the explanation target becomes clearer, and reconcile it before the final response so completed work does not remain stale.</action> </actions> <validation>A todo list exists and matches the explanation-only scope of the run.</validation> </step> <step number="1"> <title>Identify the explanation target</title> <description>Determine what the user is trying to understand: behavior, architecture, rationale, location, or relationships between components.</description> <actions> <action>Read the question carefully and identify the primary subject of the explanation.</action> <action>Infer the likely code areas, interfaces, or documentation needed to answer accurately.</action> <action>If the question is underspecified, narrow it using repository context before asking for clarification.</action> </actions> <validation>You can name the specific code or architectural topic that needs to be explained.</validation> </step> <step number="2"> <title>Ground the answer in repository truth</title> <description>Read the relevant files and inspect the real implementation before answering.</description> <actions> <action>Before reading or explaining code inside any repository path, read the applicable repo-local `AGENTS.md` guidance for that path. In shared-root workspaces, first read the generated workspace-root `AGENTS.md`, then discover tracked child-repo guidance with `git -C <repo-dir> ls-files -- AGENTS.md '**/AGENTS.md'`, and read the repo root `AGENTS.md` through the nearest ancestor file for the path being explained.</action> <action>When switching repositories or moving into a different subtree with its own `AGENTS.md`, re-check and read the newly applicable repo-local guidance before continuing.</action> <action>Open the most relevant source files, types, configuration, and nearby code paths.</action> <action>Trace enough surrounding context to explain both direct behavior and important dependencies.</action> <action>Prefer repository evidence over assumptions or generic explanations.</action> </actions> <validation>The explanation is backed by the applicable repo-local `AGENTS.md` guidance and concrete repository findings rather than guesswork.</validation> </step> </steps> </phase> <phase name="implementation"> <description>Construct the explanation itself in a way that is accurate, digestible, and matched to the user’s depth of need.</description> <steps> <step number="1"> <title>Explain what the code does</title> <description>Describe the actual behavior, responsibilities, and flow of the relevant code in plain but technically accurate language.</description> <actions> <action>Explain the main behavior before diving into details.</action> <action>Break complex systems into digestible parts or short sections.</action> <action>Use concrete repository examples when they materially improve clarity.</action> </actions> <validation>A technically literate reader can understand the behavior of the code after reading the explanation.</validation> </step> <step number="2"> <title>Explain why it is designed that way</title> <description>Surface architectural intent, tradeoffs, or conventions when they are inferable from the codebase.</description> <actions> <action>Call out important patterns, abstractions, or responsibilities and why they likely exist.</action> <action>Differentiate confirmed repository facts from higher-level interpretation when needed.</action> <action>Use analogies sparingly and only when they improve understanding.</action> </actions> <validation>The answer covers both behavior and rationale instead of stopping at a superficial walkthrough.</validation> </step> </steps> </phase> <phase name="validation"> <description>Check the explanation for accuracy, proportional depth, and response-shape discipline.</description> <steps> <step number="1"> <title>Validate explanation accuracy</title> <description>Ensure the final answer matches the actual repository findings and does not overclaim.</description> <actions> <action>Cross-check the explanation against the files that were read.</action> <action>Remove speculation that is not adequately grounded by the repository.</action> <action>If uncertainty remains, state it explicitly instead of presenting it as fact.</action> </actions> <validation>The explanation is faithful to the repository and explicit about any uncertainty.</validation> </step> <step number="2"> <title>Match the depth to the question</title> <description>Provide enough depth to be useful without front-loading unnecessary detail.</description> <actions> <action>For simple questions, answer directly with a short paragraph or a few bullets.</action> <action>For deeper questions, include more structure and more concrete code references.</action> <action>Do not overwhelm the user with exhaustive detail unless they clearly want it.</action> </actions> <validation>The answer matches the user’s likely depth needs and remains readable.</validation> </step> <step number="3"> <title>Handle artifact-worthy explanations deliberately</title> <description>Create a durable write-up only when the user clearly wants one or when the explanation truly benefits from persistent structure.</description> <actions> <action>Do not create an artifact by default.</action> <action>If a durable write-up would help, mention it instead of forcing it.</action> <action>When an artifact is created, provide a brief self-contained summary and include the returned link.</action> </actions> <validation>Artifact creation is deliberate, user-aligned, and not overused.</validation> </step> </steps> </phase><completion_criteria><criterion>The explanation is grounded in actual source files or repository artifacts.</criterion><criterion>The answer explains both what the code does and why it is structured that way when that rationale is inferable.</criterion><criterion>The response remains explanation-only and does not drift into implementation.</criterion><criterion>The answer’s depth matches the user’s question and does not overexplain by default.</criterion></completion_criteria></workflow><best_practices><guideline priority="high"><rule>Read the actual code before explaining it.</rule><rationale>Repository-grounded explanations are more accurate and more useful than generic summaries.</rationale><exceptions>Only skip deep reading when the user asks an obviously superficial question already answered by immediately visible context.</exceptions></guideline><guideline priority="high"><rule>Explain both behavior and rationale when the code supports it.</rule><rationale>Users usually want more than a mechanical walkthrough; they want to understand why the system is shaped that way.</rationale><exceptions>If rationale is not inferable from the repository, say so rather than invent it.</exceptions></guideline><guideline priority="high"><rule>Match explanation depth to the user’s apparent need.</rule><rationale>Explanation quality comes from giving the right amount of detail, not the maximum amount.</rationale><exceptions>Provide more depth when the user explicitly asks for thoroughness or when the topic is too complex for a short answer.</exceptions></guideline></best_practices><patterns> <pattern name="repository_grounded_explanation"> <description>Answer a code question by reading the relevant files first and then explaining behavior from actual repository evidence.</description> <context>Use for architectural questions, implementation questions, and “where/how does this work?” questions.</context> <template>identify subject -> read relevant files -> extract behavior and dependencies -> explain with concrete examples</template> </pattern> <pattern name="progressive_depth_response"> <description>Start with the direct answer and expand only as much as the user needs.</description> <context>Use for explainer responses unless the user explicitly asks for a deep write-up.</context> <template>short direct answer -> a few supporting bullets or paragraphs -> mention deeper follow-up path if useful</template> </pattern></patterns><decision_guidance><principles><principle>Prefer codebase truth over generic explanation.</principle><principle>Prefer clarity over exhaustiveness.</principle><principle>Prefer explicit uncertainty over invented rationale.</principle><principle>Prefer explanation over implementation.</principle></principles><constraints><constraint>Do not mutate repository-tracked state while answering.</constraint><constraint>Do not present speculation as confirmed architecture or intent.</constraint><constraint>Do not create artifacts by default.</constraint></constraints><boundaries><rule>This workflow handles understanding and explaining repository behavior, architecture, patterns, and design decisions.</rule><rule>This workflow does not handle implementation, repository mutation, branch creation, or pull request creation.</rule><rule>When the user shifts from understanding to asking for changes, do not implement from this skill. Read `implement-changes` before any mutating step and continue under that workflow instead. This handoff is mandatory.</rule></boundaries></decision_guidance><error_handling><scenario name="insufficient_repository_context"><problem>The question cannot be answered accurately because the relevant code path or source of truth is still unclear.</problem><causes><cause>The question is broad and spans multiple plausible subsystems.</cause><cause>The repository structure differs from the initial assumption.</cause></causes><recovery>Continue repository exploration, narrow the question to the most likely implementation path, and state remaining uncertainty if it cannot be fully resolved.</recovery></scenario><scenario name="rationale_not_explicit_in_code"><problem>The code makes behavior clear but does not make the original design intent fully explicit.</problem><causes><cause>The rationale was not documented in code or nearby comments.</cause><cause>Multiple plausible motivations exist for the current design.</cause></causes><recovery>Explain the confirmed behavior first, then clearly label any rationale as inference rather than guaranteed fact.</recovery></scenario></error_handling>
roocodeinc/roomote/tree/main/packages/cloud-agents/src/server/workflows/skills/standard/explain-repo-code commit fc0fbdde94
Frequently asked questions
Run npx skillmds@latest add roocodeinc/explain-repo-code in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Explanation-only repository workflow. Use when the user asks to understand behavior, architecture, or rationale from source context without modifying files. It is listed under DevOps & Infra on SkillMD.
This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
RooCodeInc (@roocodeinc) published this skill. Their other Agent Skills are listed on their SkillMD profile.