About

Imported from shipshitdev/skills (skills/how/SKILL.md). Install upstream with npx skills add shipshitdev/skills --skill how. Copyright stays with the author (MIT).

How

Name: how
Author: shipshitdev

Explore the codebase to answer "how does X work?" Produce an architectural explanation at the level of a senior engineer onboarding onto a subsystem.

Two modes:

Explain (default). Explore and produce a clear explanation.
Critique. Explain first, then spawn independent critics.

Companion to why. This skill answers what the code does. why answers what forces led to its shape.

Contract

Inputs:

A how-question: subsystem, feature flow, architectural overview, or runtime trace

Outputs:

The structured explanation below
In Critique mode, a lead verdict over critic findings

Creates/Modifies:

None

External Side Effects:

None. Read-only exploration.

Confirmation Required:

None

Delegates To:

None. May spawn read-only explorer, explainer, and critic subagents.

Explain mode

Step 1. Understand the question

Parse the ask. If ambiguous, state the best-guess interpretation and proceed. Do not ask. Let the user redirect.

Simple (one module, a narrow function): skip explorer agents. The explainer explores and explains in one pass.

Complex (multiple files or services, a cross-cutting feature): spawn 2-4 parallel explorers, then one explainer. When in doubt, lean simple.

Step 2a. Explore (complex only)

Decompose into 2-4 distinct slices so explorers do not duplicate work. Spawn all explorers in one message on the fast cheap tier, read-only. Each explorer gets references/explorer-prompt.md plus its slice. Each traces input to output without hand-waving.

Step 2b. Direct explain (simple)

Spawn one read-only explainer on the strongest judgment tier. It explores and writes the explanation. Use references/explainer-prompt.md.

Step 3. Synthesize (complex only)

Once explorers return, spawn one explainer on the strongest judgment tier with all findings. It reconciles overlap and contradictions.

Step 4. Present

Present the explainer's output. Light edits for clarity are fine. Do not substantially rewrite.

Output format

Overview. 1-2 paragraphs. What it is, what it does, why it exists.

Key Concepts. The types, services, or abstractions needed to follow the rest.

How It Works. The flow: trigger, steps, data, decision points. Prose, not pseudocode. Cite files and functions.

Where Things Live. A brief map of the relevant files.

Gotchas. Non-obvious edges and historical scars.

Critique mode

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

Run the full explain flow.
Spawn one architectural critic per available judgment family, all in one message, read-only, on mixed capability tiers. Each gets the explanation, file paths, references/critic-prompt.md, and references/critique-rubric.md.
Lead judgment. Categorize findings: Act on, Consider, Noted, Dismissed. Present the explanation first, then the critique.

How procedure

Read how procedure when running this workflow. Apply the authorized scope and mode of this entry point to every step. Resolve other skills through this distribution’s active catalog; resolve resources relative to the installed skill directory.

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/shipshitdev-skills-how/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

shipshitdev-skills-how.ocm.jsonjson

{
  "ocm": "1",
  "id": "shipshitdev-skills-how",
  "kind": "skill",
  "name": "how",
  "description": "Walk through how a subsystem works. Use for \"how does X work\", code walkthroughs before changing something, and placement or ownership questions. Explains architecture, runtime flow, and onboarding mental models. Can critique architecture. Use why for motivation.",
  "publisher": "shipshitdev",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "coding",
      "hr"
    ],
    "tags": [
      "skill-md",
      "architecture",
      "walkthrough",
      "onboarding",
      "critique",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Walk through how a subsystem works. Use for \"how does X work\", code walkthroughs before changing something, and placement or ownership questions. Explains architecture, runtime flow, and onboarding mental models. Can critique architecture. Use why for motivation."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/shipshitdev/skills",
      "path": "skills/how/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/shipshitdev/skills/blob/HEAD/skills/how/SKILL.md",
      "key": "shipshitdev/skills/skills/how/SKILL.md"
    },
    "license": "MIT"
  },
  "instructions": "# How\n\nExplore the codebase to answer \"how does X work?\" Produce an architectural\nexplanation at the level of a senior engineer onboarding onto a subsystem.\n\nTwo modes:\n\n1. **Explain** (default). Explore and produce a clear explanation.\n2. **Critique.** Explain first, then spawn independent critics.\n\nCompanion to `why`. This skill answers what the code does. `why` answers\nwhat forces led to its shape.\n\n## Contract\n\nInputs:\n\n- A how-question: subsystem, feature flow, architectural overview, or\n  runtime trace\n\nOutputs:\n\n- The structured explanation below\n- In Critique mode, a lead verdict over ",
  "cost": {
    "context_tokens": 832
  }
}

Fetch it by URL: GET /api/v1/registry/shipshitdev-skills-how/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.