token-codebase-exploration
Use when exploring an unfamiliar codebase, understanding how a specific feature or pattern works, or learning how components interact. Provides the exploration workflow and strategy.
- License 许可
- BSD-3-Clause
- 最近更新
- 2026-11-11
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- token-codebase-exploration
- version
- 1.3.1
- description
- Use when exploring an unfamiliar codebase, understanding how a specific feature or pattern works, or learning how components interact. Provides the exploration workflow and strategy.
- allowed-tools
- Bash, Read, Grep, Glob
03 SKILL.md 正文
Token Codebase Exploration
Step 1: Determine Targeted vs Broad Before Reading Anything
| User request | Approach |
|---|---|
| "Help me understand this project" | Broad |
| "How is this codebase organized?" | Broad |
| "How does the AuthService work?" | Targeted |
| "How do I implement this pattern here?" | Targeted |
| "Show me examples of X" | Targeted |
| "What patterns are used in this project?" | Broad → then Targeted |
Never start reading files before making this determination.
Targeted Learning (when user asks "how does X work" or "show me examples of Y")
Follow these 5 steps in order. Do not skip ahead to reading.
Step 1: Extract the concept from the user's request and identify the likely file names or terms to search for.
Step 2: Search — do not read files yet. Use grep and find to locate candidates. Anchor grep patterns to exclude comment lines.
Step 3: Rank examples — prefer files with self-documenting names and explicit variable
names over short, dense files. A 35-line file with clear names teaches a pattern better
than an 8-line file with abbreviations. Use wc -l only as a tiebreaker between files
of similar readability, not as the primary criterion.
Step 4: Read 2–3 selected examples fully — not more. One simple or minimal example, one standard example, and one advanced example only if the pattern has genuinely different variations.
Step 5: Extract and explain the pattern — never just show code. Explain what the pattern does conceptually, what elements are required, and the common pitfalls specific to this codebase.
Broad Exploration (when user asks to understand the whole project)
Work through these phases in order. Read only what each phase requires.
Phase 1 — Structure overview (no Read yet):
tree -L 2 || find . -maxdepth 2 -type d | head -30 # tree with fallback if absent
ls -la
cat README.md # this is the legitimate first Read
Phase 2 — Entry point: identify the main executable or initialization file for this language and framework. Read the entry point — this is file 1.
Phase 3 — Core abstractions: search for interface definitions and abstract base classes without reading files. These reveal the architecture's vocabulary.
Phase 4 — Most-used components and recent activity: identify what modules are depended on most frequently (via import/using analysis) and which files have been modified recently (via git log). These two signals together locate the active core of the project.
Read order after the entry point: one core service or business logic file → one infrastructure file (repository, adapter, external interface). That is files 2 and 3.
Stop at 5 Files — Then Summarize
After reading 5 files, STOP. The limit is not about context window saturation (5 typical files use approximately 2% of the available context window). The limit exists to force a consolidation step: reading without summarizing produces worse answers than reading 5 files, articulating what you now understand, and then reading 2 more with a specific question in mind.
Summarize findings and state what you now understand. Then read further only with a specific question that summary leaves open.
04 同仓库更多 Skills
write-guide
Use when writing a guide someone else will follow - a method guide, a playbook, a how-we-do-it document for a team or a client - or when reworking, auditing or extending one that already exists. Also when an outline is handed to you to fill in, when a guide's rules need evidence labels, or when a second guide joins the first and the two start contradicting each other.
write-french
Use when the output is French - a chat reply in French, or a French markdown deliverable such as a guide, a report or a synthesis - including when the user writes in French and expects French back. Prevents French that reads as translated English: word-for-word calques, sentences compressed until the meaning is gone, jargon used before it is defined, invented turns of phrase.
verify-sources
Use when about to state a factual, technical, historical, or procedural claim in ANY domain (software, DIY/craft, health, legal, finance...) - a version number, default value, statistic, API behavior, a legal deadline, a health claim, a manufacturer spec, "X always/never does Y", "the docs say", "best practice is" - that you have not verified against a source this turn, or when tempted to answer a factual question from memory under time pressure
token-file-ops
Use when reading, editing, creating, or manipulating files; or running commands with potentially large output. Provides generic bash-first patterns for any file type.
teach
Use when the user sets learning a topic or skill as their own goal - "teach me X", "I want to learn X", "help me get good at X", a course or study plan for themselves. Not for a question one reply answers ("what is X", "explain X").
search-first
Use before writing any script, config, workflow or service that automates a task or connects two systems - even when a standard approach seems obvious. Search for an existing tool, package, GitHub Action or service first, then adopt, extend, compose or build.