Code is read 10x more than it's written. Reading code is a skill you actively develop — not a passive activity.
Codebase Onboarding Order
Always explore a new codebase in this order:
README — What does it do? How do I run it?
Package/dependency files — What tools and frameworks are used?
Entry point — Where does execution start? (main.ts, index.js, app.py)
Core domain models — What are the main data structures?
Key user flows — Trace one important feature end-to-end
Tests — Tests reveal intended behavior and edge cases
Config/env files — What is configurable? What are the environments?
Code Tracing Method
For understanding a specific flow:
1. Start from the trigger (user action, API call, scheduled job)
2. Follow the execution path step by step
3. Note: what data flows in? what comes out?
4. Identify where external systems are called
5. Mark where business logic lives vs. infrastructure
Questions to Ask While Reading
What is this component responsible for? (single responsibility check)
What does it need to run? (dependencies)
What does it produce/return?
What could make it fail?
Why was it written this way? (check git blame/history for context)
Using AI for Code Reading
"Explain what this function does, including:
- What it takes as input
- What it returns
- Any side effects
- Non-obvious behavior I should know about"
"Walk me through how [feature] works,
starting from [entry point] to [output]"
"What would I need to understand to safely
modify [specific part] of this code?"
Navigating Large Codebases
Search patterns — use grep/ripgrep to find usages of a function/class
Git blame — who changed this and why?
Git log — when was this introduced? what changed over time?
Tests — run tests while reading to see what behavior is expected
Dependency graph — which modules depend on what?
Warning Signs While Reading
Functions longer than 50 lines (doing too much)
Deep nesting (> 3 levels) — logic is hard to follow
Many parameters (> 4) — likely needs refactoring
Comments explaining WHAT (should be obvious) vs WHY (actually useful)
No tests — higher risk, be extra careful when modifying
1---2name: code-reading3description: Code Reading4---56# Code Reading78## Core Principle9Code is read 10x more than it's written. Reading code is a skill you actively develop — not a passive activity.1011---1213## Codebase Onboarding Order1415Always explore a new codebase in this order:161. **README** — What does it do? How do I run it?172. **Package/dependency files** — What tools and frameworks are used?183. **Entry point** — Where does execution start? (main.ts, index.js, app.py)194. **Core domain models** — What are the main data structures?205. **Key user flows** — Trace one important feature end-to-end216. **Tests** — Tests reveal intended behavior and edge cases227. **Config/env files** — What is configurable? What are the environments?2324---2526## Code Tracing Method2728For understanding a specific flow:29```301. Start from the trigger (user action, API call, scheduled job)312. Follow the execution path step by step323. Note: what data flows in? what comes out?334. Identify where external systems are called345. Mark where business logic lives vs. infrastructure35```3637---3839## Questions to Ask While Reading4041- What is this component responsible for? (single responsibility check)42- What does it need to run? (dependencies)43- What does it produce/return?44- What could make it fail?45- Why was it written this way? (check git blame/history for context)4647---4849## Using AI for Code Reading5051```52"Explain what this function does, including:53- What it takes as input54- What it returns 55- Any side effects56- Non-obvious behavior I should know about"5758"Walk me through how [feature] works, 59starting from [entry point] to [output]"6061"What would I need to understand to safely 62modify [specific part] of this code?"63```6465---6667## Navigating Large Codebases6869- **Search patterns** — use grep/ripgrep to find usages of a function/class70- **Git blame** — who changed this and why?71- **Git log** — when was this introduced? what changed over time?72- **Tests** — run tests while reading to see what behavior is expected73- **Dependency graph** — which modules depend on what?7475---7677## Warning Signs While Reading7879- Functions longer than 50 lines (doing too much)80- Deep nesting (> 3 levels) — logic is hard to follow81- Many parameters (> 4) — likely needs refactoring82- Comments explaining WHAT (should be obvious) vs WHY (actually useful)83- No tests — higher risk, be extra careful when modifying
Run npx skillmds@latest add jamestorrevillas/code-reading 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.
Code Reading It is listed under Coding & Dev Tools on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Capability flags: docs only. 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.
jamestorrevillas (@jamestorrevillas) published this skill. Their other Agent Skills are listed on their SkillMD profile.
jamestorrevillas