skills.rest
petemcw
petemcwCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

but-how

Explains how code subsystems work by synthesizing parallel codebase explorations into architectural walkthroughs.

Updated Sep 13, 2026
Search Tags:#architecture#onboarding#code explanation#codebase exploration#subsystem#mental model#code walkthrough
One-click install
npx skills add https://github.com/petemcw/farseer --skill but-how-petemcw
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: but-how
Source: https://github.com/petemcw/farseer/tree/main/skills/but-how
Command: npx skills add https://github.com/petemcw/farseer --skill but-how-petemcw

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Engineers joining a new codebase or touching an unfamiliar subsystem waste hours tracing code paths by hand. This Skill answers "how does X work" questions by exploring the codebase and producing a structured architectural explanation a senior engineer can use to build a working mental model. ## Core Features & Use Cases - Adaptive exploration depth: Routes simple questions (single module, narrow function) to a single explainer pass, and complex subsystem questions to 2-4 parallel read-only explorer agents whose findings are synthesized. - Structured explanations: Produces consistent output sections — Overview, Key Concepts, How It Works, Where Things Live, Gotchas — with file paths, function names, and optional mermaid diagrams. - Placement and layering guidance: Answers "where should this live", "which package owns this", and "is this the right layer" questions alongside runtime flow walkthroughs. - Use Case: Before modifying an authentication flow, ask how token refresh works and receive a synthesized explanation tracing the entry point, call chain, key abstractions, and non-obvious pitfalls. ## Quick Start Ask how the payment retry logic works in this repository and get a structured architectural explanation.

Frequently Asked Questions about but-how

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I understand how an unfamiliar codebase subsystem works?▼

Ask a "how does X work" question and the skill explores the codebase, tracing entry points, call chains, and key abstractions. Complex questions spawn parallel explorer agents whose findings are synthesized into one structured explanation with file and function references.

How to decide where new code should live in a project?▼

Ask placement, ownership, or layering questions such as "which package owns this" or "is this the right layer". The skill maps the subsystem's boundaries and existing structure so you can place new code consistently with current architecture.

When does the skill use multiple explorer agents versus one?▼

Simple questions about a single module or narrow function use one explainer in a single pass. Complex questions spanning multiple files, services, or cross-cutting features spawn 2 to 4 parallel read-only explorers, then a synthesizer merges their findings.

What sections does the code explanation output include?▼

Explanations use five sections: Overview, Key Concepts, How It Works, Where Things Live, and Gotchas. Sections that do not apply are dropped, and mermaid or ASCII diagrams are included only when they clarify multi-component flows.

Can the exploration agents modify my code?▼

No. All explorer and explainer subagents run in read-only mode using Read, Grep, and Glob. They gather facts and write explanations without changing any files in the repository.

Related Skills

Explore More Software Engineering Skills→
LayerDynamicsLayerDynamics

outline-understanding-user-request

Analyze code files to formulate targeted clarifying questions about scope and integration.

Community
Intermediate
Sma1lboySma1lboy
136

how

Explains codebase architecture and subsystem flows using parallel explorer and critic agents.

Community
Advanced
tvishwanadhatvishwanadha

adr

Centralize Architecture Decision Records with superseding and amending workflows.

Community
Intermediate
HX-InfratstructureHX-Infratstructure

graft

Query a precomputed code graph to locate, understand, and trace repository symbols.

Official
Intermediate