agentleFS
pantheon-orgpantheon-org/tekhne/skills/software-engineering/how/SKILL.md

how

Skill10 starsChanged 40 days agoMITView on GitHub

Ported from the how skill in cursor/plugins pstack — Cursor, a separate AI-coding-editor product, not to be confused with a text/DB cursor — for use with this harness's Agent tool. Agent-spawning mechanics below use this repo's actual subagent types (Explore, general-purpose) and Claude model/effort params (sonnet/opus/haiku/fable, low/medium/high/xhigh/max) in place of the original's model names specific to that other editor, and its readonly flag. One more adaptation, not cosmetic: the original has every explorer/synthesizer/critic use Glob/Grep/Read directly. If your environment has…

98 other projects use a version of this, 66 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use setup-pstack, ketchup-video and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • bnemaSkill

    setup-pstack

    Configure which Pi models pstack uses per role. Detects available provider/model specs and writes pstack's user configuration. Use for /setup-pstack, "configure pstack models", or changing pstack model choices.

    Also in 25 projects that use this

  • tristanphvnSkill

    ketchup-video

    Catch the user up like /keel:ketchup, with a short silent video of slides for what happened and the waiting calls as text under it. Use for /keel:ketchup-video.

    Also in 13 projects that use this

  • ianclearySkill

    principle-explain-the-number

    Apply before you trust, report, or act on a number you measured: a speedup, a regression, a throughput, a latency, or an eval result. Find what limits it, and rule out that it measured something other than the work you think.

    Also in 28 projects that use this

  • ianclearySkill

    poteto-help

    Guides users through pstack setup, /poteto-mode, and picking the skill, playbook, or principle for a task. Type /poteto-help with a question.

    Also in 14 projects that use this

  • eryzerzSkill

    make-bot-ui

    Use when building a custom UI (page, dashboard, buttons) that should wake a Grok Bot over a webhook, when the user must provide a webhook sender key, or when exposing that UI on Tailscale.

    Also in 19 projects that use this

  • drafaelSkill

    in-your-own-words

    Restate the user's goals and the problem they are trying to solve to check understanding. Manual invocation only; use when the user explicitly invokes in-your-own-words or requests this understanding check. Do not solve the task or rewrite the assistant's last answer.

    Also in 26 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. 0 are common, 8 are distinctive, and 6 are very specific to this project.

  • 0

    Common

    Most of the 97 edited versions we read keep these.

  • 8

    Distinctive

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    No code-graph MCP is required — Glob/Grep/Read work, a code-graph tool (e.g.

    line 32
  2. Very specific:

    Before treating the explanation as done, run a spot check: pick one non-obvious claim and re-run tokensave_context on it to confirm the …

    line 49
  3. Distinctive:

    Write the explanation for a senior engineer who has never seen this subsystem — assume no prior context, but don't re-explain language or …

    line 54
  4. Distinctive:

    When in doubt, lean simple.

    line 78
  5. Very specific:

    Start broad: call tokensave_context with its exploration angle as the task, in plain English

    line 100
  6. Very specific:

    Follow the thread: from what comes back, trace the call chain (callers, callees, data flow, type definitions) using …

    line 101
  7. Distinctive:

    Stop when it can describe the full path from input to output (or trigger to effect) without hand-waving any step

    line 104
  8. Very specific:

    Read references/explainer-prompt.md for the communication style and output format.

    line 118
  9. Distinctive:

    Before presenting, verify: pick at least one non-obvious claim in the explanation and re-run the code-graph query (or re-read the source …

    line 135
  10. Distinctive:

    Follow this structure, adapted to the question.

    line 141
  11. Distinctive:

    Run the full explain flow above (Steps 1-4).

    line 160
  12. Distinctive:

    After the explanation is complete, spawn several independent architectural critics in a single message so they run concurrently and don't …

    line 164
  13. Very specific:

    Read references/critic-prompt.md for the prompt template.

    line 173
  14. Distinctive:

    NEVER: do line-level code review in critique mode.

    line 219

“Common” is measured: kept by at least 6 in 10 of the 97 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

How

Ported from the how skill in cursor/plugins pstack — Cursor, a separate AI-coding-editor product, not to be confused with a text/DB cursor — for use with this harness's Agent tool. Agent-spawning mechanics below use this repo's actual subagent types (Explore, general-purpose) and Claude model/effort params (sonnet/opus/haiku/fable, low/medium/high/xhigh/max) in place of the original's model names specific to that other editor, and its readonly flag.

One more adaptation, not cosmetic: the original has every explorer/synthesizer/critic use Glob/Grep/Read directly. If your environment has a code-graph MCP (e.g. tokensave, code-review-graph), prefer its structural query tools (tokensave_context and friends) over raw file search — they return relevant source directly and track symbols across renames, which Glob/Grep/Read cannot do. Every codebase-reading step below names the code-graph tool first and Glob/Grep/Read as the fallback when no such tool is connected. If your code-graph tool supports a per-worktree index, re-index the current worktree before relying on it — a stale index can silently omit symbols only changed there.

Explore the codebase to answer "how does X work?" questions. Produce clear architectural explanations at the level of a senior engineer onboarding onto a subsystem. Enough to build a working mental model, not annotated source code.

Two modes:

  1. Explain (default). Explore the codebase and produce a clear explanation
  2. Critique. Explain first, then spawn multiple independent reviewers to identify architectural issues

Prerequisites

  • A question scoped to this codebase, not a general architecture question with nothing to explore
  • For critique mode specifically: the explanation from Explain mode already produced, since critique never runs standalone
  • No code-graph MCP is required — Glob/Grep/Read work, a code-graph tool (e.g. tokensave) is just cheaper when one is connected

When to Use

  • "How does X work?" — a subsystem, feature flow, or architectural overview.
  • "Walk me through what happens when..." — a runtime trace through the codebase.
  • Placement/ownership/layering questions: "where should this live", "which package owns this", "is this the right layer".
  • Architecture critique: "what's wrong with this design", "critique this architecture" — always after an explanation, never standalone.

When NOT to Use

  • The question is about design rationale or history ("why was this built this way") — use why instead.
  • The question is about whether a change is safe to ship ("what could this break") — use blast-radius instead.
  • The question has nothing to explore in this codebase (a general architecture question with no concrete target).

Verification

Before treating the explanation as done, run a spot check: pick one non-obvious claim and re-run tokensave_context on it to confirm the output still matches what the explanation says. Run this check the same way you'd run tests before shipping code — confirm the actual output agrees with the claim, don't just trust the first pass.

Mindset

  • Write the explanation for a senior engineer who has never seen this subsystem — assume no prior context, but don't re-explain language or framework fundamentals
  • tokensave_context's returned source is the ground truth for a claim; a symbol's name, a stale comment, or an explorer's paraphrase is not
  • In critique mode, an empty critique is a valid, honest outcome — don't manufacture a finding just to justify having spawned critics
  • State your best-guess interpretation of an ambiguous question and proceed; let the user redirect rather than blocking on a clarifying question first

Explain Mode

Step 1. Understand the Question and Assess Complexity

Parse what the user is asking about:

  • "How does the rate limiter work?", a subsystem
  • "How do we handle billing for on-demand usage?", a feature flow
  • "How is the auth service structured?", an architectural overview
  • "Walk me through what happens when a user submits a form", a runtime trace

Identify the scope. If ambiguous, state your best-guess interpretation before exploring. Don't ask. Let the user redirect if you're off.

Assess complexity to decide the approach:

  • Simple (a single module, a small utility, a narrow question like "how does function X work"): skip explorer agents; explore and explain in a single pass yourself, or one agent. Go to Step 2b.
  • Complex (a subsystem spanning multiple files/services, a cross-cutting feature, a full architectural overview): spawn parallel explorer agents first, then hand off to a synthesizer. Go to Step 2a.

When in doubt, lean simple. You can always spawn explorers if the explainer hits a wall.

Step 2a. Explore (complex questions only)

Decompose the question into 2-4 parallel exploration angles, each a distinct slice of the subsystem so explorers don't duplicate work. Example split for "how does the rate limiter work?":

  • Explorer 1: data model and state management
  • Explorer 2: request path and enforcement
  • Explorer 3: configuration and metrics infrastructure

The right decomposition depends on the question. Use your judgment. Narrow questions: 2 explorers is fine. Broad subsystems: up to 4.

Spawn all explorers in a single Agent message so they run concurrently:

  • subagent_type: Explore (its tool grant is "everything except Agent/Artifact/ExitPlanMode/Edit/Write/NotebookEdit" — that includes MCP tools generally, tokensave_* among them; there's no separate "read-only MCP tools only" filter, so the no-Read/Grep/Glob constraint below is a prompt instruction the explorer follows, not a tool restriction the harness enforces)
  • model: omit to inherit the session model unless the subsystem is unusually large or unfamiliar, in which case set a higher-effort model explicitly

Each explorer gets the same base prompt from references/explorer-prompt.md plus a specific exploration angle naming its slice. If a code-graph MCP is connected, each explorer's exploration tool should be its context-query tool (e.g. tokensave_context, supplemented by tokensave_search/tokensave_callees/tokensave_callers/tokensave_impact for depth) rather than Glob, Grep, Read, or list_directory — the source sections it returns are the relevant code. Without a code-graph MCP, fall back to Glob/Grep/Read. Each explorer should:

  • Start broad: call tokensave_context with its exploration angle as the task, in plain English
  • Follow the thread: from what comes back, trace the call chain (callers, callees, data flow, type definitions) using tokensave_callees/tokensave_callers/tokensave_impact as needed, and further tokensave_context calls for anything the first pass didn't cover — passing seen_node_ids from each response into the next call's exclude_node_ids
  • Trust the returned source, don't guess from symbol names alone
  • Stop when it can describe the full path from input to output (or trigger to effect) without hand-waving any step
  • Note things that are surprising, non-obvious, or that a newcomer would get wrong

Each explorer returns structured findings: components found, flow traced, files/symbols consulted, anything non-obvious. Overlap between explorers is fine; the synthesizer reconciles.

Then proceed to Step 3.

Step 2b. Direct Explain (simple questions)

For a narrow question, either explore and write the explanation yourself in one pass, or spawn a single agent:

  • subagent_type: Explore for the exploration, or general-purpose if you want the agent to also draft the writeup
  • model: omit to inherit the session model

Read references/explainer-prompt.md for the communication style and output format. Same structure as the synthesizer below, just no explorer findings as input — the agent does its own exploration (via a code-graph MCP's context-query tool when one is connected, otherwise Glob/Grep/Read) and writes the explanation directly.

Proceed to Step 4.

Step 3. Synthesize (complex questions only)

Once all explorers return, spawn a single agent to synthesize their findings into one coherent explanation:

  • subagent_type: general-purpose (needs to reconcile/verify against the codebase, not just search)
  • model: omit to inherit the session model, or escalate (e.g. opus, effort high) for a large or contentious subsystem

The synthesizer gets all explorers' findings and writes the human-facing explanation (output format below). Read references/explainer-prompt.md for the full prompt template. It reconciles overlapping findings, resolves contradictions, and weaves the slices into a unified picture — verifying against the codebase via the code-graph MCP when one is connected, raw Read/Grep/Glob otherwise.

Step 4. Present

Before presenting, verify: pick at least one non-obvious claim in the explanation and re-run the code-graph query (or re-read the source directly) to confirm it still says what the explanation says it says. This is cheap and catches the case where an explorer's summary drifted from what the code actually returned. Then present the synthesizer's output to the user. You may lightly edit for clarity or add context from the conversation, but don't substantially rewrite. The explanation is the product.

Output Format

Follow this structure, adapted to the question. Not every section is needed for every question.

Overview. 1-2 paragraphs. What it is, what it does, why it exists. Enough to decide whether to keep reading.

Key Concepts. The important types, services, or abstractions. Brief definition of each. Not exhaustive, just the ones needed to understand the rest.

How It Works. The core of the explanation. Walk through the flow: what triggers it, what happens step by step, where data goes, the decision points. Prose, not pseudocode. Reference specific files and functions so the reader can go look, but don't dump code blocks unless a snippet is genuinely necessary.

Where Things Live. A brief map of the relevant files/directories. Not every file, just the ones needed to start working in this area.

Gotchas. Non-obvious or surprising things that would trip someone up. Historical context that explains why something looks weird. Known sharp edges.

Critique Mode

Triggered when the user asks for architectural issues, problems, or improvements, not just understanding.

Step 1. Explain First

Run the full explain flow above (Steps 1-4). You must understand the architecture before critiquing it.

Step 2. Spawn Critics

After the explanation is complete, spawn several independent architectural critics in a single message so they run concurrently and don't see each other's output. Vary the model and/or reasoning effort across critics so they read the architecture from genuinely different angles rather than converging on the same take — for example: sonnet/high, opus/xhigh, sonnet/max, fable/high. Three or four critics is usually enough; scale down for a small subsystem.

For each critic:

  • subagent_type: general-purpose (needs to check the actual code, not just search)
  • model / effort: one distinct combination per critic, per above

Read references/critic-prompt.md for the prompt template. Each critic gets:

  1. The explanation from Step 1 (so they don't re-explore)
  2. The relevant file paths (so they can pull the actual code via tokensave_context/tokensave_node, not raw Read)
  3. The architectural critique rubric from references/critique-rubric.md

Step 3. Lead Judgment

You're a pragmatic lead, not an aggregator.

Categorize findings:

  • Act on. Architectural problems worth fixing now
  • Consider. Real concerns, but the cost/benefit is unclear
  • Noted. Valid observations, low priority
  • Dismissed. Wrong, missing context, or style preference

Present the explanation first (from Step 1), then the critique verdict below it. The explanation should stand on its own; someone who just wants to understand the system shouldn't wade through critique.

Troubleshooting

  • The code-graph query returns nothing relevant to the question: try a narrower search for the specific symbol name instead of a broad task description, or adjust the path scope — don't fall back to Glob/Grep/Read just because the first call came up empty.
  • Explorers contradict each other: the synthesizer re-checks the disputed point directly against the source rather than picking whichever explorer sounded more confident.
  • A question that looked narrow turns out to span multiple files once you start exploring: switch to the complex-question path (parallel explorers, Step 2a) mid-stream rather than forcing a single-pass explanation to cover ground it can't.
  • Critics converge on the same finding despite varied model/effort combinations: that's a legitimate corroboration signal, not a sign something went wrong — note it as strongly confirmed rather than suspicious.
  • The subsystem is too large for even 4 explorer angles to cover: narrow the question back to the user rather than spawning more agents than the 2-4 range calls for; ask which part matters most.

Common Failure Modes to Avoid

NEVER conclude what a symbol does from its name alone.

WHY: tokensave_context returns the actual source; a name can be stale, misleading, or copied from an unrelated pattern elsewhere in the codebase. The returned code is the source of truth, not the identifier.

NEVER dump a large code block into the explanation just because you have it.

WHY: the explanation should read as prose a senior engineer can follow without cross-referencing a wall of code. A snippet earns its place only when it clarifies something prose genuinely can't.

NEVER let critics see each other's findings before each submits their own, in critique mode.

WHY: seeing another critic's output invites anchoring toward the same conclusions, defeating the point of spawning several independent reviewers with deliberately varied model/effort combinations.

NEVER do line-level code review in critique mode.

WHY: critique mode is scoped to architectural problems — abstraction fit, data model, boundary discipline, evolution readiness. Line-level nits are a different job and dilute the critic's signal.

NEVER flag missing abstraction, or suggest a rewrite, without naming the concrete problem it would solve.

WHY: "this could use more abstraction" or "this should be rewritten" with no demonstrated problem is the single most common valueless finding in architecture review — it isn't actionable and erodes trust in the rest of the critique.

NEVER flag a deliberate, well-reasoned tradeoff as an architectural issue just because an alternative exists.

WHY: architecture is built from tradeoffs. Penalizing a sound one for not being the only possible choice produces noise, not signal — an empty critique is a valid, honest outcome when the architecture holds up.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.