Workflow & Core Tools · cursor/plugins

how

Name: how
Author: cursor/plugins

Use for "how does X work", code walkthroughs before changing something, and placement / ownership / layering questions ("where should this live", "which package owns this", "is this the right layer"). Explains subsystem architecture, runtime flow, onboarding mental models. Use why for motivation.

L2 Local · Restricted workspaceV1 Commit-PinnedWrite FileDual-pass Audit

Author cursorGitHub cursor/plugins ↗Stars 7221License 仓库根无统一 LICENSE（GitHub API license 为 null）；该 skill 随 pstack 插件分发，插件自带 pstack/LICENSE（MIT，Copyright (c) 2026 Lauren Tan）Commit df3fb154fb

Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

Pure prompt orchestration, zero scripts, zero assets: how's SKILL.md only defines "how to decompose and delegate". All code reading is offloaded to host Task subagents, using two built-in prompt templates (explorer/explainer) as the sole reference.

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.

Positioned as a "senior engineer onboarding-level mental model", intentionally excluding line-by-line blow-by-blow annotations—this serves as the anchor for output quality.

Complexity routing: simple questions directly output via a single-pass explainer; complex questions first spawn 2-4 parallel explorers to slice and investigate deeply from different angles, then aggregate via the explainer; when in doubt, default to the simple path.

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.

Parallelism is determined by the actual complexity of the question; 'When in doubt, take the simple path.' prevents making a fuss over small issues and idling multiple subagents.

Explorers are strictly read-only, parallel, and dispatched in a single batch message: one generalPurpose subagent per lane, model picked from config (default grok-4.6-fast-xhigh), readonly is permanently true—the exploration tier is designed as a side-effect-free fact collector.

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

Below the same section, items are listed: subagent_type: generalPurpose, model: your configured how-explorer model (default `grok-4.6-fast-xhigh`), readonly: true—all three spawn blocks (2a/2b/3) are marked readonly.

Explorer output adheres to a fixed-structure fact contract (Components Found / Flow / Files Read / Boundaries / Non-Obvious Things / Open Questions), enforcing hard requirements: "no guessing when reading code" and "honestly admit breakpoints".

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.

The template ends with 'Return your findings in this structure…Reference exact file paths, function names, type names, and line numbers where relevant.' and '"I couldn't determine how X connects to Y" is better than making something up.'—structured outputs ensure the explainer can cross-verify without sugarcoating.

The explainer is responsible for reconciliation and re-verification: when multiple explorer findings overlap or conflict, the explainer inspects the code independently before drafting the explanation, granted read-only re-inspection permissions (Read/Grep/Glob) without needing to re-explore from scratch.

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.

This turns 'parallel slicing → synthesis' into a two-tier pipeline: explorers aim for depth, the explainer aims for integration, and conflicts are resolved against source code.

Output format and presentation discipline: explanations follow fixed sections (Overview/Key Concepts/How It Works/Where Things Live/Gotchas, collapsible); complex flows permit mermaid/ASCII diagrams but forbid decorative charts; the frontend only lightly polishes without heavy rewriting.

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.

The section list is explicitly defined in the Output Format section of SKILL.md; diagram rules are in explainer-prompt.md: 'Use mermaid (```mermaid) for structured flows…A diagram should clarify, not decorate.'

Trigger surface is restricted to explicit user invocation, with configurable model roles: frontmatter declares disable-model-invocation: true, and model defaults can be overridden by pstack persistent model rules.

pstack/skills/how/SKILL.md

disable-model-invocation: true

The source of 'your configured how-explorer model' is explicitly stated in other pstack skills: setup-pstack/SKILL.md specifies 'Write `~/.cursor/rules/pstack-models.mdc`, an always-applied rule that sets pstack's model per role.', and interrogate/SKILL.md cites the same path; how itself only declares defaults and fallback semantics without writing files.

2Core Capabilities

01Code walkthrough explanations (how does X work / subsystem architecture / runtime flow)

02Placement / ownership / layering judgments (where should this live / which package owns this / is this the right layer)

03Single-pass direct answers for simple questions (no subagents spawned)

042-4 way parallel read-only exploration consolidated into a unified synthesis for complex questions

05End-to-end read-only discipline (both explorer and explainer have readonly: true)

06Anti-hallucination verification: explorers must actually read the code and list Files Read; explainers may independently re-check to resolve conflicts

07On-demand diagramming: mermaid (structured flows) or ASCII (simple relations), decorative diagrams prohibited

4Recommended Governance & Evidence

Suggested Controls for Safe Operation

For Agent Runtime

Restrict working directory

For Administrators

Retain operation logs

Evidence & Triggers (File Paths & Excerpts)

本地文件: Operate on local project files or workspace artifacts

Audit Notes: . Attack surface = read-only access to local codebases by readonly subagents under the host Task, plus local model configuration injected via persistent rules (~/.cursor/rules/pstack-models.mdc, model names only, no credentials); no script execution, no outbound network calls, no credential reading, no local writes; disable-model-invocation: true ensures invocation is exclusively explicit by the user (/how). Note: readonly is a prompt-level constraint, and subagent read scope is bounded by host authorization.

5Second-Pass Verification

[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]，已在正文限定表述。

6Verdict & Scenarios

Read-only delegation isolates the cost and risk of code reading inside readonly subagents, preventing the main session from being flooded with large source snippets and yielding only a single consolidated explanation.

The two-tier 'parallel slicing → single synthesizer' architecture yields genuine speedups and depth benefits for complex subsystems, resolving contradictions via source code re-inspection rather than voting.

Contract-driven output: fixed sections + anti-hallucination + honest breakpoint reporting ensure explanations can be verified by readers or other agents down to specific files and functions.

Zero dependencies and zero writes, allowing whole-directory migration across hosts; integrates naturally with the pstack family (why/teach/poteto-mode) via description and model rules.

Best for: Ideal for building a mental model before touching unfamiliar code: onboarding to cross-service or cross-module subsystems, 'why does this logic run this way', new team member onboarding, or explaining architecture to subsequent agents or humans; also suitable as a reusable read-only exploration primitive for other engineering skills (already adopted by teach).

Not for: Not suitable for motivation/trade-off/historical context questions (description explicitly routes these to why: 'Use why for motivation.'); not suitable when persistent documentation artifacts are required (answers only, does not write; use teach or other documentation-writing skills instead); not suitable for tiny, trivial one-off queries (the simple path skips subagents but remains heavyweight); not suitable when running code to verify runtime behavior is needed (purely static code reading; use verification skills for dynamic behavior).

Install Agent-Ready

① Verified Mirror 2026-09-09

Option A · Direct DownloadDownload how.tar.gz

sha256: ee70ff35028506ef…

Option B · Copy Guide for Agent

install.json

Agents automatically download and verify mirrors from this JSON guide.

② Upstream GitHub

GitHub Repo ↗

Pinned to commit df3fb154fb.