1实现原理 · 为什么它能做到
纯 prompt 编排、零脚本零资产：how 的 SKILL.md 只规定『如何拆解与委派』，所有读代码的动作都交给宿主 Task 子代理，自带两个 prompt 模板（explorer/explainer）作为唯一参照物。
pstack/skills/how/SKILL.md
Explore the codebase to answer "how does X work?" questions. Produce architectural explanations at the level of a senior engineer onboarding onto a subsystem, enough to build a working mental model, not so much that it reads like annotated source code.
注：定位是『senior engineer onboarding 级心理模型』，刻意排除逐行注释式流水账——这是输出质量的锚。
复杂度路由：简单问题单遍 explainer 直出；复杂问题先按 2-4 个角度并行派 explorer 切片深挖，再交给 explainer 合成；拿不准默认走简单路径。
pstack/skills/how/SKILL.md
**Simple** (a single module, a small utility, a narrow question such as "how does function X work"): no explorers. One explainer explores and explains in a single pass. Go to Step 2b.
注：并行度由问题真实复杂度决定；'When in doubt, take the simple path.' 防止小题大做、空转多个子代理。
explorer 全部只读、并行、一次消息齐发：每路一个 generalPurpose 子代理，model 取配置（默认 grok-4.6-fast-xhigh），readonly 恒为 true——探查层被设计成无副作用的事实采集器。
pstack/skills/how/SKILL.md
Decompose the question into 2 to 4 exploration angles, each a distinct slice of the subsystem. Spawn all explorers in a single message
注：同段下方逐项列出 subagent_type: generalPurpose、model: your configured how-explorer model (default `grok-4.6-fast-xhigh`)、readonly: true——三处 spawn 块（2a/2b/3）全部标注 readonly。
explorer 产出是固定结构的事实契约（Components Found / Flow / Files Read / Boundaries / Non-Obvious Things / Open Questions），并把『读代码不许猜』与『诚实承认断点』写成硬要求。
pstack/skills/how/references/explorer-prompt.md
Start by finding the relevant code. Use Glob to find directories and files, Grep to find key symbols, Read to understand the actual implementation. Don't guess from names. Read the code.
注：模板尾部另有 'Return your findings in this structure…Reference exact file paths, function names, type names, and line numbers where relevant.' 与 '"I couldn't determine how X connects to Y" is better than making something up.'——输出结构化是为了让 explainer 能交叉核对，不许粉饰。
explainer 负责调停与再验证：多路 explorer 发现重叠或矛盾时，explainer 先自行查码消解再写解释，且被授予只读复查权（Read/Grep/Glob），不需要从零重探。
pstack/skills/how/references/explainer-prompt.md
Their findings will overlap in places and may occasionally contradict. Reconcile them. Merge overlapping descriptions, resolve contradictions by checking the code yourself, and combine the separate slices into a unified picture.
注：这是把『并行切片→合并』做成两级流水线：explorer 求深，explainer 求整合，矛盾以源码为准。
输出格式与呈现纪律：解释按固定章节（Overview/Key Concepts/How It Works/Where Things Live/Gotchas，可裁剪），复杂流允许 mermaid/ASCII 图但禁装饰性图；前台只做轻度润色，禁止大幅改写。
pstack/skills/how/SKILL.md
Present the explainer's output to the user. Light edits for clarity or context from the conversation are fine. Do not substantially rewrite it.
注：章节清单在 SKILL.md Output Format 段原文列出；图的使用规则在 explainer-prompt.md：'Use mermaid (```mermaid) for structured flows…A diagram should clarify, not decorate.'
触发面收窄为用户显式调用，且模型角色可配置：frontmatter 声明 disable-model-invocation: true，模型默认值可被 pstack 常驻模型规则覆盖。
pstack/skills/how/SKILL.md
disable-model-invocation: true
注：『your configured how-explorer model』的配置来源在 pstack 家族其它 skill 明文：setup-pstack/SKILL.md 'Write `~/.cursor/rules/pstack-models.mdc`, an always-applied rule that sets pstack's model per role.'、interrogate/SKILL.md 同引该路径；how 自身只声明默认值与回退语义，不写文件。
2核心能力
01代码走读式解释（how does X work / 子系统架构 / 运行时流）
02放置/归属/分层判断（where should this live / which package owns this / is this the right layer）
03简单问题单遍直答（不派子代理）
04复杂问题 2-4 路并行只读探查后统一合成
05只读纪律贯穿全链（explorer 与 explainer 均 readonly: true）
06反编造查证：explorer 必须实读代码并列出 Files Read，explainer 允许自行复查消解矛盾
07按需图示：mermaid（结构化流）或 ASCII（简单关系），禁止为装饰而图
4风险提醒 风险提醒：蓝色 · 知晓即可
风险提醒：蓝色 · 知晓即可
- readonly 是提示词级约束：若宿主对 Task 子代理不做强制只读隔离，探查者可读范围等于宿主授权，理论上可越出仓库。 — readonly: true 为 SKILL.md 声明值，非宿主强制机制 [INFERENCE]
- 解释质量强依赖模型：并行切片若各自误读，explainer 的『自行复查消解』是唯一纠错闸，模型弱时会放大共识性误读。 — explainer-prompt.md 只授权复查，不强制全量重读
- 知识时效性：结论只对当前 checkout 有效，代码库漂移后旧解释会误导；skill 无刷新机制（每次现读，属设计使然）。 — 无缓存/版本化机制
风险提醒：蓝色，知晓即可。接触面=宿主 Task 下 readonly 子代理对本地代码库的只读访问，以及经由常驻规则注入的本地模型配置（~/.cursor/rules/pstack-models.mdc，仅模型名、非凭证）；无脚本执行、无网络外发、无凭证读取、无本地写入；disable-model-invocation: true 仅用户显式调用（/how）。注意点：readonly 为提示词级约束、子代理读范围以宿主授权为界。
5第二遍独立确认
- [ok] 纯 prompt、无脚本资产 — 技能目录仅 SKILL.md + references/explorer-prompt.md + references/explainer-prompt.md 三个 markdown，无 scripts/data/模板之外文件。
- [ok] 复杂度路由与默认简单路径 — SKILL.md 原文 'When in doubt, take the simple path.' 存在；Simple→2b、Complex→2a→3 的流程编号自洽。
- [ok] 2-4 路并行 explorer + 单一 explainer 合成 — 原文 'Decompose the question into 2 to 4 exploration angles'、'Spawn all explorers in a single message'、'synthesize their findings into one explanation' 逐字在。
- [ok] readonly 贯穿 — Step 2a/2b/3 三处均列 '- `readonly`: `true`'；模板无任何写盘/执行指令。
- [ok] explorer 输出契约与反编造要求 — explorer-prompt.md 含完整小节标题（Components Found 等六个）、'Don't guess from names. Read the code.'、以及 'is better than making something up' 原文。
- [ok] explainer 调停矛盾 + 只读复查 — 原文 'resolve contradictions by checking the code yourself' 与 'You have read-only access to the codebase' 均在。
- [ok] 输出格式/呈现纪律 — SKILL.md 列出的五章节与模板 Output Format 一致；'Light edits for clarity…do not substantially rewrite it.' 逐字存在。
- [ok] 模型可配置（how-explorer/how-explainer） — how 内仅声明默认值；配置写入/读取路径在 setup-pstack（写 ~/.cursor/rules/pstack-models.mdc）与 interrogate/arena/swarm（读同文件）一致，机制真实存在；角色键 how-explorer/how-explainer 的逐键映射未在 pstack 内单点列出，属『规则文件按角色键注入』的通用机制 [INFERENCE]，已在正文限定表述。
6结论
适合：适合改动任何不熟悉代码前先建心理模型的场景：跨服务/跨模块子系统上手、'这段逻辑为什么这样走'、新成员 onboarding、把架构讲给下一个 agent 或人；也适合作为其它工程 skill 的只读探查原语被复用（teach 已这样用）。
不适合：不适合动机/权衡/历史背景类问题（description 明确交给 why：'Use why for motivation.'）；不适合需要留下文档产物的场景（它只答不写，要落盘应选 teach 或其它写文档的 skill）；不适合极小的一次性疑问（简单路径虽省子代理，仍偏重）；不适合需要跑代码验证行为的场景（纯静态读码，动态行为请用验证类 skill）。
安装 agent 直装可复制
① 本站镜像 更新 2026-09-09
方式 A · 人下载镜像包下载 how.tar.gz
sha256:
方式 B · JSON 格式安装指南，复制给 agentee70ff35028506ef…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② 上游 GitHub · 原始来源
来源信息 GitHub 原始
作者 / 仓库cursor / cursor/plugins
原始 GitHubcursor/plugins ↗
Stars7221
最近推送2026-09-09
本 skill commit
df3fb154fb许可仓库根无统一 LICENSE（GitHub API license 为 null）；该 skill 随 pstack 插件分发，插件自带 pstack/LICENSE（MIT，Copyright (c) 2026 Lauren Tan）
本站信息
收录日期2026-09-06
分类基础工具与工作流
侦查报告AI 侦查 · 2 遍 · 2026-09-06
本站镜像与 GitHub 原始是不同来源：本站锁定 commit 快照经 /r2 分发；GitHub 为实时上游，内容可能已更新。