explain

Authors and runs layered explainer docs that teach complex technical topics through interactive checkpoints.

1|1|Updated Jul 23, 2026
One-click install
npx skills add https://github.com/nearmap/shipyard --skill explain-nearmap
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: explain
Source: https://github.com/nearmap/shipyard/tree/main/skills/explain
Command: npx skills add https://github.com/nearmap/shipyard --skill explain-nearmap

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Engineers often hit gnarly topics — a recurring bug family, a subtle design constraint, an unfamiliar system — that no one has time to explain properly. This Skill turns one of those topics into a verified, layered explainer doc and then walks you through it interactively until you genuinely understand it, ending in a decision rather than a lecture. ## Core Features & Use Cases - Isolated investigation and authoring: Delegates research to an isolated subagent so file reads and repro attempts never clutter your session, producing a verified explainer doc with claims marked as verified versus inferred. - Interactive layered walkthrough: Runs an existing explainer doc one layer per turn with an explicit checkpoint after each layer, so you control the pace and can ask questions in place. - Live challenge handling: When you push back on a claim, it designs and runs a discriminating experiment live, correcting the doc if the evidence contradicts it. - Use Case: After a confusing gate or CI finding, run the author mode on that bug family to produce a durable explainer doc, then walk it layer by layer in a fresh session before merging. ## Quick Start Ask the assistant to explain the topic behind your latest CI failure by invoking the explain skill with that topic as the argument.

Frequently Asked Questions about explain

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

FAQPage Schema
How do I create an explainer doc for a complex bug or system?▼

Invoke the explain skill with the topic as its argument. It delegates the investigation to an isolated subagent, which writes a layered explainer doc to the topic's scratch directory and returns a compact brief with the doc path and verification counts.

How do I run an existing explainer doc interactively?▼

Pass the path to an existing explainer doc as the skill's argument. It walks the doc one layer per turn with an explicit checkpoint after each layer, letting you continue, ask questions, challenge claims, or skip ahead.

What happens when I challenge a claim during an explainer session?▼

The session stops asserting and designs a discriminating experiment whose outcome differs between the doc's claim and yours, then runs it live. If the evidence contradicts the doc, the doc is corrected and the walk continues from the corrected ground.

Does the explain skill write anything to Jira or GitHub?▼

No. The skill never reads or writes the issue tracker at any point. The session is about your understanding, not the project record, so nothing from it lands on a ticket.

When should I not use an interactive explainer session?▼

Avoid it when you only need a quick factual answer rather than deep understanding, since the format is one layer per turn with checkpoints. It is designed for gnarly topics that warrant a verified doc and a decision at the end.