AGENT SKILL

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

NormandErwan
NormandErwan/Claude

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.

★ 1
NormandErwan
NormandErwan/Claude

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.

★ 1
NormandErwan
NormandErwan/Claude

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

★ 1
NormandErwan
NormandErwan/Claude

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.

★ 1
NormandErwan
NormandErwan/Claude

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").

★ 1
NormandErwan
NormandErwan/Claude

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.

★ 1