Preflight Readme Scan

Forces a lightweight README reconnaissance before any broad code exploration or multi-file modification in an unfamiliar repository. Use at the start of every new conversation on a project the agent has not yet read, whenever the user asks an open-ended question like "this project does what / how do I add X / where is Y", and before the agent would otherwise reach for SemanticSearch, Glob, or repeated Grep passes to understand the codebase. Reads the top-level README.md first, then only the folder-level README.md files relevant to the task, explicitly skipping dependency / cache / data folders. Cuts token cost significantly compared to ad-hoc exploration because each folder README is a pre-organized structural index.

playerrch Updated Sep 22, 2026

Install

Press C to copy

$ npx skillmds@latest add playerrch/preflight-readme-scan

Installs into ~/.claude/skills (or .claude/skills inside a project). Restart Claude Code to pick it up.

Download SKILL.md

＋ Add to plugin

README badge

[![SkillMD](https://skillmd.com/badge/playerrch/preflight-readme-scan.svg)](https://skillmd.com/skills/playerrch/preflight-readme-scan)

Trust & safety

Audits pending

Not yet audited · commit bca9c50

Permissions this skill uses

Reads secrets
The instructions read tokens, keys, or other credentials.

Works with: Claude Code Claude.ai OpenAI Codex +

File contents

Preflight README Scan

新 agent 进入一个陌生/不熟的项目时，第一步永远是读 README，而不是盲目 Grep / Glob / SemanticSearch。本 skill 给出"何时读、读到什么程度、跳过什么"的判断树。

为什么省 token

做法	等价 token 消耗	信息密度
1 次 Read 顶层 README.md	约 5-15 KB	高（已按目录分类）
1 次 SemanticSearch 宽泛查询	约 10-30 KB × 多轮可能	低（chunk 碎片、含无关内容）
多次 Glob + Read 扫文件	累积 50-200 KB	最低（文件本身含大量噪声）

项目里的顶层 README 通常已经是一张"导航表"，直接链到各子 README；子 README 再分别给出该目录的职责、文件清单、约束。这套结构是人为精心整理过的结构化索引，远比机器扫出来的搜索结果省。

决策树：要不要预读

任务输入到手
  ├─ 任务里明确给出了具体文件 (如 "改 backend/routes/auth.py 的 X") ？
  │   └─ 是 → 跳过 README 预读，直接 Read 目标文件 (Level 0)
  │
  ├─ 任务仅涉及回答概念问题、不改代码？
  │   └─ 是 → 跳过 README 预读，直接回答或用 SemanticSearch 定位 (Level 0)
  │
  ├─ 同一对话里已经读过顶层 README？
  │   └─ 是 → 跳过重复 (Level 0)
  │
  ├─ 任务跨越多个模块、需理解架构？
  │   └─ 是 → Level 2 (顶层 + 2-3 个相关子 README)
  │
  ├─ 用户问 "这个项目是干啥的 / 从哪入手 / 介绍一下"？
  │   └─ 是 → Level 2 或 Level 3（用户若要"全貌"则 Level 3）
  │
  └─ 其它正常任务
      └─ Level 1（只读顶层 README 拿目录导航）

四档预读强度

Level 0 — 不预读

任务文件已锁定
任务是纯回答、只读、不改动代码
已经在同一会话里读过 README

直接进入正常工具链（Read / Grep / SemanticSearch）。

Level 1 — 最小预读（默认）

Read 项目根 README.md
扫它的"目录导航"或"Directory Structure"章节
把导航表记到心里 → 后续若要定位某个模块，直接 Read 对应子 README
不要一口气读所有子 README（浪费）

Level 2 — 定向深读（推荐用于多模块任务）

Level 1 的 1-3 步
根据任务关键字匹配 2-3 个子目录，Read 它们的 README.md
- 例："改答疑流程" → 读 backend/README.md + backend/routes/README.md + frontend/README.md
- 例："新增一张表" → 读 backend/README.md + backend/migrations/README.md
若子 README 里指向 docs/<具体文档>.md 规范，按需追读（最多再 1-2 篇）

Level 3 — 全景扫读（仅在用户明确要求"梳理全局"时）

顶层 README
顶层导航表里列出的所有子 README
docs/README.md + 它指向的核心规范文档（CURRICULUM / SECURITY / DEPLOYMENT 等）

这一档适合做重构规划、写新手入门材料、项目交接；日常小任务不应触发。

永远不读的目录（强制跳过名单）

不要读这些目录下的 README（即使存在也要跳过）：

node_modules/, venv/, .venv/, Include/, Lib/, Scripts/, site-packages/
__pycache__/, .pytest_cache/, .mypy_cache/, .ruff_cache/
dist/, build/_work/, build/Output/, target/
volumes/ 下的容器数据子目录（Dify / Postgres / Redis 等持久化）
.git/

阅读顺序的标准模板

Phase 1: Orient     (Level 1 默认)
  └─ Read README.md (项目根)

Phase 2: Focus      (Level 2 按需)
  ├─ Read <dir_a>/README.md
  ├─ Read <dir_b>/README.md
  └─ （必要时）Read docs/<relevant>.md

Phase 3: Execute    (开始真正的查代码/改代码)
  └─ 到这里才用 Read 具体源码、Grep、SemanticSearch 等

反模式（不要这么做）

预读后还盲搜：已经读了 README 知道"出题逻辑在 backend/routes/question.py"，就不要再用 SemanticSearch "where is question generation"
Level 1 被当 Level 3 使：单纯改 1 个方法的小任务却读了 15 个 README，浪费令牌
重复预读：同一会话里 README 内容不会变，读过就不要再读
忽略 README 直冲代码：陌生项目不读 README 就开始 Glob，信息密度低而且容易误会模块边界
读依赖目录的 README：Lib/site-packages/xxx/README.md 是第三方库文档，不是你的项目信息

在任务回复中的体现

预读完成后，首次回应用户的内容里应当包含：

对项目/相关模块的一句话自我定位，让用户知道你已经理解上下文
不需要事无巨细说你读了哪些 README（除非用户问过程）
后续不要再为"了解项目"而做广搜

与其它 skill 的配合

协同 skill	触发时机
`maintain-folder-readmes`	完成改动后，根据本 skill 读过的 README 反向校对：哪些 README 与新现实不符需要更新
`cleanup-deprecated-artifacts`	如果本 skill 预读时发现某 README 里提到的文件已经不存在，顺手列入清理候选

实战示例

用户：「帮我给答疑模块加一个管理员查询接口。」

正确做法（Level 2）：

Read 项目根 README.md → 看到 backend/routes/ 里有 qa.py
Read backend/routes/README.md → 确认 qa.py 前缀 /api/qa，权限走 require_permission
Read backend/security/README.md → 确认 require_permission("qa:xxx") 的用法
这时才 Read backend/routes/qa.py 找 router 对象，加新端点

错误做法：

SemanticSearch "where is QA handler defined"（20 KB 噪声）
Glob **/qa*.py（拿到一堆测试文件也要分辨）
SemanticSearch "how to add permission check"（又一堆碎片）
在一堆零散结果里拼出该怎么做

前者每次任务稳定省掉 50% 以上的探索令牌，后者每次都在重新摸黑。

最后一条规则

当有了 README 这个结构化索引，就优先用它。把 SemanticSearch 留给"README 之外仍需要确认的具体实现细节"，而不是"从零理解项目"的用途。

---name: preflight-readme-scandescription: Forces a lightweight README reconnaissance before any broad code exploration or multi-file modification in an unfamiliar repository. Use at the start of every new conversation on a project the agent has not yet read, whenever the user asks an open-ended question like "this project does what / how do I add X / where is Y", and before the agent would otherwise reach for SemanticSearch, Glob, or repeated Grep passes to understand the codebase. Reads the top-level README.md first, then only the folder-level README.md files relevant to the task, explicitly skipping dependency / cache / data folders. Cuts token cost significantly compared to ad-hoc exploration because each folder README is a pre-organized structural index.---# Preflight README Scan新 agent 进入一个陌生/不熟的项目时，**第一步永远是读 README**，而不是盲目 Grep / Glob / SemanticSearch。本 skill 给出"何时读、读到什么程度、跳过什么"的判断树。## 为什么省 token| 做法 | 等价 token 消耗 | 信息密度 ||---|---|---|| 1 次 Read 顶层 README.md | 约 5-15 KB | 高（已按目录分类） || 1 次 SemanticSearch 宽泛查询 | 约 10-30 KB × 多轮可能 | 低（chunk 碎片、含无关内容） || 多次 Glob + Read 扫文件 | 累积 50-200 KB | 最低（文件本身含大量噪声） |项目里的顶层 README 通常已经是一张"导航表"，直接链到各子 README；子 README 再分别给出该目录的职责、文件清单、约束。这套结构是人为精心整理过的**结构化索引**，远比机器扫出来的搜索结果省。## 决策树：要不要预读```任务输入到手 ├─ 任务里明确给出了具体文件 (如 "改 backend/routes/auth.py 的 X") ？ │ └─ 是 → 跳过 README 预读，直接 Read 目标文件 (Level 0) │ ├─ 任务仅涉及回答概念问题、不改代码？ │ └─ 是 → 跳过 README 预读，直接回答或用 SemanticSearch 定位 (Level 0) │ ├─ 同一对话里已经读过顶层 README？ │ └─ 是 → 跳过重复 (Level 0) │ ├─ 任务跨越多个模块、需理解架构？ │ └─ 是 → Level 2 (顶层 + 2-3 个相关子 README) │ ├─ 用户问 "这个项目是干啥的 / 从哪入手 / 介绍一下"？ │ └─ 是 → Level 2 或 Level 3（用户若要"全貌"则 Level 3） │ └─ 其它正常任务 └─ Level 1（只读顶层 README 拿目录导航）```## 四档预读强度### Level 0 — 不预读- 任务文件已锁定- 任务是纯回答、只读、不改动代码- 已经在同一会话里读过 README直接进入正常工具链（Read / Grep / SemanticSearch）。### Level 1 — 最小预读（默认）1. Read 项目根 `README.md`2. 扫它的"目录导航"或"Directory Structure"章节3. 把导航表记到心里 → 后续若要定位某个模块，直接 Read 对应子 README4. **不要**一口气读所有子 README（浪费）### Level 2 — 定向深读（推荐用于多模块任务）1. Level 1 的 1-3 步2. 根据任务关键字匹配 2-3 个子目录，Read 它们的 `README.md` - 例："改答疑流程" → 读 `backend/README.md` + `backend/routes/README.md` + `frontend/README.md` - 例："新增一张表" → 读 `backend/README.md` + `backend/migrations/README.md`3. 若子 README 里指向 `docs/<具体文档>.md` 规范，按需追读（最多再 1-2 篇）### Level 3 — 全景扫读（仅在用户明确要求"梳理全局"时）1. 顶层 README2. 顶层导航表里列出的所有子 README3. `docs/README.md` + 它指向的核心规范文档（CURRICULUM / SECURITY / DEPLOYMENT 等）这一档适合做重构规划、写新手入门材料、项目交接；日常小任务不应触发。## 永远不读的目录（强制跳过名单）不要读这些目录下的 README（即使存在也要跳过）：- `node_modules/`, `venv/`, `.venv/`, `Include/`, `Lib/`, `Scripts/`, `site-packages/`- `__pycache__/`, `.pytest_cache/`, `.mypy_cache/`, `.ruff_cache/`- `dist/`, `build/_work/`, `build/Output/`, `target/`- `volumes/` 下的容器数据子目录（Dify / Postgres / Redis 等持久化）- `.git/`## 阅读顺序的标准模板```Phase 1: Orient (Level 1 默认) └─ Read README.md (项目根)Phase 2: Focus (Level 2 按需) ├─ Read <dir_a>/README.md ├─ Read <dir_b>/README.md └─ （必要时）Read docs/<relevant>.mdPhase 3: Execute (开始真正的查代码/改代码) └─ 到这里才用 Read 具体源码、Grep、SemanticSearch 等```## 反模式（不要这么做）- **预读后还盲搜**：已经读了 README 知道"出题逻辑在 `backend/routes/question.py`"，就不要再用 SemanticSearch "where is question generation"- **Level 1 被当 Level 3 使**：单纯改 1 个方法的小任务却读了 15 个 README，浪费令牌- **重复预读**：同一会话里 README 内容不会变，读过就不要再读- **忽略 README 直冲代码**：陌生项目不读 README 就开始 Glob，信息密度低而且容易误会模块边界- **读依赖目录的 README**：`Lib/site-packages/xxx/README.md` 是第三方库文档，不是你的项目信息## 在任务回复中的体现预读完成后，首次回应用户的内容里应当包含：- 对项目/相关模块的**一句话自我定位**，让用户知道你已经理解上下文- 不需要事无巨细说你读了哪些 README（除非用户问过程）- 后续不要再为"了解项目"而做广搜## 与其它 skill 的配合| 协同 skill | 触发时机 ||---|---|| `maintain-folder-readmes` | 完成改动后，根据本 skill 读过的 README 反向校对：哪些 README 与新现实不符需要更新 || `cleanup-deprecated-artifacts` | 如果本 skill 预读时发现某 README 里提到的文件已经不存在，顺手列入清理候选 |## 实战示例用户：「帮我给答疑模块加一个管理员查询接口。」**正确做法（Level 2）**：1. Read 项目根 `README.md` → 看到 `backend/routes/` 里有 `qa.py`2. Read `backend/routes/README.md` → 确认 `qa.py` 前缀 `/api/qa`，权限走 `require_permission`3. Read `backend/security/README.md` → 确认 `require_permission("qa:xxx")` 的用法4. 这时才 Read `backend/routes/qa.py` 找 `router` 对象，加新端点**错误做法**：1. SemanticSearch "where is QA handler defined"（20 KB 噪声）2. Glob `**/qa*.py`（拿到一堆测试文件也要分辨）3. SemanticSearch "how to add permission check"（又一堆碎片）4. 在一堆零散结果里拼出该怎么做前者每次任务稳定省掉 50% 以上的探索令牌，后者每次都在重新摸黑。## 最后一条规则**当有了 README 这个结构化索引，就优先用它**。把 SemanticSearch 留给"README 之外仍需要确认的具体实现细节"，而不是"从零理解项目"的用途。

playerrch/cursor-agent-skills/tree/main/skills/通用/preflight-readme-scan commit bca9c50b77

Frequently asked questions

npx skillmds@latest add playerrch/preflight-readme-scan