Source Code Walkthrough

English | 简体中文

An instruction-based agent skill for turning source code into a readable, evidence-backed tutorial. It follows one concrete example from the user's input to the final output, then explains the architecture and core APIs that support that journey.

Instead of starting in the middle of a library or listing function names, the walkthrough explains what the user wants to accomplish, how the program starts, why each step is needed, and how the data changes.

What it covers

• End-to-end execution: the actual CLI command, HTTP request, or user script; configuration and object construction; business logic; storage or external-service boundaries; and the user-visible result.
• Code and data together: complete function signatures, actual arguments and effective defaults, key source excerpts, and concrete before/after values.
• Architecture and APIs: module responsibilities, dependencies, data models, public APIs, internal interfaces, and extension points, including side effects and failure behavior.
• Evidence and uncertainty: distinguish observed execution from source-based inference and unresolved behavior. Record the version or commit and link to source locations and available runtime evidence.
• Readable explanations: introduce unfamiliar concepts when they become necessary and connect each step to the next in plain language.

This is a reusable workflow for a coding agent, not a standalone analyzer or tracing executable. The agent uses its available repository, terminal, and other tools. No Python package or model subscription is required by the skill itself; running a target project may require its own dependencies and authorized services.

Files

source-code-walkthrough/
├── SKILL.md                   # Instructions and activation description
├── agents/openai.yaml         # Codex display metadata and example prompt
├── assets/report-template.md  # Adaptable report template
├── README.md
└── README.zh-CN.md

The canonical instructions and report template are currently written in Chinese. The skill instructs the agent to follow the user's language; explicitly ask for an English report when needed. The English README does not imply a separate English implementation.

Install in Codex

Clone this repository with a local folder name matching the skill identifier:

git clone https://github.com/ZYTech97/execution-walkthrough-skill.git source-code-walkthrough

The GitHub repository is named execution-walkthrough-skill; the skill's identifier and invocation remain source-code-walkthrough and $source-code-walkthrough.

Download or clone the repository containing this folder. Copy the whole source-code-walkthrough folder into .agents/skills/ in the project you want to analyze. Keep the template and metadata alongside SKILL.md; do not copy only the entry file.

For example, from the target project's root, replace /path/to/source-code-walkthrough with the actual downloaded skill directory:

mkdir -p .agents/skills
test ! -e .agents/skills/source-code-walkthrough && cp -R /path/to/source-code-walkthrough .agents/skills/source-code-walkthrough

The existence check prevents this example from replacing an existing installation. Review and back up an existing folder before updating it. Check /skills in Codex CLI; restart Codex if the skill does not appear. See the official local skill documentation for discovery locations and installation options.

Use it

Open the target codebase in your coding agent and provide a concrete request:

Use $source-code-walkthrough to explain this repository in English.
Choose a small existing example, trace it from the user's input to the
final output, and explain the architecture and core APIs.
Save the tutorial to a new Markdown file under docs/.
Use source inspection only; do not run external services.

To follow an existing runnable example:

Use $source-code-walkthrough to trace examples/demo.py.
Run it with the already configured local test dependencies, record the
key function calls and input/output transformations, and analyze the
architecture and core APIs. Save the report as docs/demo-walkthrough.md.
Do not call paid models or write to production systems.

For live model or database testing, explicitly authorize the services, data, and spending limits. A request to read source code alone is not authorization to make paid calls or production writes. If execution is unavailable, the report should still explain the source-supported path and clearly identify what was not verified.

What the report looks like

The report starts with the example's purpose and input, then follows the execution chain. Each key step explains its purpose before showing the complete signature and actual call, the important source code, and the resulting data or state changes. It also explains who receives the result and why the next step is necessary.

The architecture and API analysis follows the execution walkthrough. The closing evidence index records sources, execution artifacts, and untested branches. The template supports this structure without requiring a rigid fill-in-the-blanks writing style.

Scope and limitations

• Static inspection can explain a potential path; it does not prove that path ran.
• Asynchronous tasks may overlap. A log's order is not automatically a guaranteed execution order.
• External service internals remain outside the observable boundary unless evidence is available.
• Preserve full parameter bindings, but summarize large objects and vectors and redact secrets. Prompt text is summarized by purpose, variables, and template location by default.
• Generated reports still need review. A successful example is not a benchmark score or a guarantee for every configuration.

Contributing

Include a concrete example of an unclear or inaccurate walkthrough and describe the expected improvement. Prefer focused changes that improve both readability and verifiability. Keep the two READMEs consistent and preserve the distinction between observed behavior and inference.