Claude-Application-Explainer

📘 Application Explainer

Turn any application repo into a searchable, self-contained Product & Engineering Guide, with every claim checked against the code.

Quick start · How it works · What it generates · Example · Development

Why

New engineers and PMs spend their first weeks piecing together how an app works from READMEs, Slack threads, and reading code. This plugin gives Claude Code a repeatable process for writing that knowledge down:

• One file to share. The guide is a single HTML file with no server, build step, or network access needed to read it.
• Grounded in the code. Claims cite repo paths, review agents fact-check every section, and anything that can't be verified is left out.
• Safe by default. The app repo is only ever read. The guide lives in its own folder and git repo, and Claude stops for your approval at every decision that matters.

Quick start

This repo is both the plugin and a single-plugin marketplace. In Claude Code:

/plugin marketplace add SimplySylvia/Claude-Application-Explainer
/plugin install application-explainer@application-explainer

Then open Claude Code in the app repo you want documented and ask, for example:

Build an onboarding guide for this repo for new engineers.

Explain this codebase: architecture, tech stack, and how we deploy.

Use the application-explainer skill on this app.

Topic guides

For one technology, run /topic-explainer (or ask for a "topic explainer") and name it:

/topic-explainer GraphQL

Build a topic explainer for React Router in this app.

You get a smaller guide covering what the technology is, its core concepts with code examples (for an API library: how to make a request, handle an error, test an endpoint), where the app uses it, a guided walkthrough of one real flow through the code, patterns and gotchas, common changes, the version the repo pins compared with the latest release, and links to the official docs, all researched online for that version.

If the repo already has a Product & Engineering Guide, Claude asks whether to build a separate topic guide (the default) or add the topic as a deep dive inside the existing guide, so your main internal doc stays current in one place. A plain question like "what is GraphQL and how does this app use it?" gets a normal answer, with an offer to build a topic guide. It never starts one on its own.

Later, when the code has changed, ask Claude to update the guide. It checks which sections cite files that changed since the guide was built and re-verifies only those.

Guide hubs

Once a repo has two or more guides, ask Claude to link them (or run new_hub.py). A hub page, <app>-guides/, features the Product & Engineering Guide and lists topic guides in a sortable table with section previews. It searches every guide's sections and headings, and keeps a "Continue reading" list. Every connected guide gets a breadcrumb back to the hub, a Guides menu, a "Search all guides" link in its own search, and the hub's light/dark setting. New guides join the hub when they're scaffolded, and every guide build refreshes it, so the hub stays current as you add and update guides. See references/hub.md.

Claude confirms the scope with you, then works through the phases below.

From a local clone:

/plugin marketplace add /path/to/application-explainer
/plugin install application-explainer@application-explainer

To try it without installing: claude --plugin-dir /path/to/application-explainer.

For agents that don't load plugins, use the kickoff prompt in skills/application-explainer/PROMPT.md.

How it works

Claude works through a checklist of nine phases: scope, scaffold, discover, write, review, screenshots, glossary, QA, and share. It writes the guide itself and hands research, fact-checking, and glossary drafting to subagents that run in parallel. It stops for your approval at each key decision, and commits the guide after every phase.

Topic guides run a shorter checklist: scope, scaffold, discover (the repo and the web in parallel), write, review, glossary, QA, and share.

See the full workflow diagrams and who does what →

Guardrails

• The app repo is read-only. Claude reports stale docs, bugs, or odd config to you instead of fixing them.
• No secrets or personal data in the guide. A suspected secret is reported by file and line only.
• Claude asks before writing anything (until you've agreed the scope), changing accounts, flags, or roles, going through OAuth consent, deploying or publishing, and capturing screens that might show real personal data.
• Topic guides keep the repo off the web. Web research runs in a separate agent that only gets the technology name, its version, and generic questions. Company and app names, paths, code, config, and data never go into a search query or URL, and fetched pages are treated as untrusted.
• The guide is internal. It documents architecture and security controls, so don't publish it publicly (see references/sharing.md).

What it generates

Claude writes to a guide folder outside the app repo (default: a sibling <app>-guide/) with its own git repo.

<app>-guide/
├── <app>-guide.html                  # the guide: one self-contained HTML file
├── <app>-guide-no-screenshots.html   # share version without screenshots (only built when screenshots exist)
├── guide_config.py                   # title, brand color, logo, parts/pages, collapse defaults
├── sections/<id>.html                # one source file per section
├── diagrams.py                       # SVG architecture/flow diagrams
├── shots.py, screenshots/            # optional screenshot gallery
├── build/                            # build engine copied from the skill (python3 build/build.py)
├── qa/                               # qa_check.py output and glossary drafts (git-ignored)
├── PROGRESS.md                       # phase checklist, scope, decisions, open questions (survives across sessions)
└── README.md                         # how to rebuild, and how the guide is shared internally

The HTML guide inlines all of its CSS, JS, icons, fonts, and images, so it opens straight from disk. It has:

• Five part pages shown as header tabs, each with a sidebar:
  • Product: overview, features (grouped by area, with route, code location, and rollout flag), site map and route tree
  • Engineering: architecture diagram, tech stack by layer with versions
  • Operations: environments, URLs, and how a change reaches production (including rollback)
  • Working process: local dev setup and daily loop, testing strategy
  • Reference: cheat sheet of commands, glossary
• Optional sections chosen to fit the app, such as request lifecycle, auth, data model, async jobs, data pipeline, observability, security, and AI features. See the full catalog in references/sections.md.
• SVG diagrams with a pan/zoom viewer.
• Code blocks with syntax highlighting and a Copy button, highlighted when the guide is built.
• A glossary of domain, vendor, and internal terms, chosen by a scout agent that reads the guide as its audience would and flags terms that need a fuller explainer. Mentions of a term link to it and show its definition on hover.
• ⌘K search across all pages.
• Dark and light themes.
• An optional screenshot gallery, captured only from an environment with synthetic data that you've approved.
• A footer recording the source repo, branch, commit, and build date.

Before Claude hands the guide over, qa_check.py must pass on both HTML files with zero TODOs.

Topic guides

A separate topic guide lives in <app>-<topic>-guide/ with the same layout (no screenshots), plus research/<topic>.md, the web research report Claude worked from. It has three pages:

• The concept: what the technology is and how it compares, then its core concepts in a table linked to the versioned docs, followed by a short highlighted code example for each.
• In <app>: a usage map with a flow diagram; a guided walkthrough of one real flow, quoting the repo lines at each step; patterns and gotchas; common changes with example code and tests.
• Reference: the version the repo pins vs. the latest release (including security fixes in between), official docs with the date each was checked, and a glossary.

As a deep dive, the same sections go on the existing guide's Topics page as one topic group (the page is created before Reference the first time, and later deep dives join it), with ids prefixed by the topic (express-walkthrough) and its terms merged into the guide's glossary. Link to it from the rest of the guide, for example from the tech stack row for that technology. guide_config.py records each topic and when its docs were last checked, and updates flag docs older than 90 days.

Example

Open the live demo: a hub for Shopfront, the small fictional app used by the evals (evals/_fixture/make-app.sh). It links a complete Product & Engineering Guide, which has an Express deep dive on its Topics page, and a separate PostgreSQL topic guide, both built by the topic explainer. A real app produces more sections and longer tables. The screenshots below are from the same demo.

The Topics page, added with the topic explainer:

The hub that links them (new_hub.py):

The Engineering page at the top of this README shows the architecture diagram in the light theme. Its caption flags a mismatch between a code comment and what the code actually does: the kind of finding the verification pass is there to catch.

Requirements

• Claude Code with plugin support
• Python 3.9+ (build engine and scripts; standard library only)
• Google Chrome or Chromium (for qa_check.py and screenshots)
• Web access, for topic guides only (the research agent reads official docs and release notes)

Repository layout

Path	What
.claude-plugin/plugin.json	Plugin manifest
.claude-plugin/marketplace.json	Marketplace manifest (lists this repo as its only plugin)
skills/application-explainer/	The skill: SKILL.md, build engine/, guide hub/ engine, starter/ template, scripts/, references/
skills/topic-explainer/	The topic skill: SKILL.md, starter/ topic template, references/ (reuses the engine and scripts above)
agents/	Subagents the skills fan out to: repo-researcher, structure-reviewer, section-verifier, glossary-scout, glossary-drafter, and for topics tech-researcher and source-verifier (web)
docs/	HOW-IT-WORKS.md workflow and agents; demo/ live demo (a hub, the main guide, and a topic guide) and their sources; images/ README screenshots (served by GitHub Pages)
evals/	claude plugin eval suite: trigger, near-miss, and end-to-end cases on a small fixture app
tests/	Unit tests for the scaffold, build, hub, diagrams, and glossary scripts
.github/	CI workflow, issue templates, and the pull request template
CHANGELOG.md · LICENSE	Release notes · MIT license

Development

Unit tests

Fast checks on the engine and scripts (standard library only, about two seconds):

python3 -m unittest discover -s tests -t tests

CI runs these on every push and pull request, along with the demo build and QA. On pull requests, it also checks that changes to skills/ or agents/ bump the version.

Evals

The suite in evals/ runs against a small fictional app that evals/_fixture/make-app.sh creates.

# Trigger and near-miss cases: does the skill fire when it should, and stay out of the way when it shouldn't?
claude plugin eval . --tag trigger nearmiss --scaffold

# End to end: builds a whole guide and runs QA (slow; grants the tools the build needs)
claude plugin eval . --tag e2e --scaffold --runs 1 --allow-tools Bash Write Edit

# Guardrails only: a planted secret is never copied, screenshots wait for a synthetic-data confirmation, and
# topic research never sends repo details to the web (that case needs web access)
claude plugin eval . --tag safety --scaffold --runs 1 --allow-tools Bash Write Edit WebFetch

Run the trigger and near-miss cases after any change to the skill's description, and the safety cases after any change to its rules.

Demo and screenshots

The live demo and the README screenshots are built with the current engine from three sources in docs/demo/: source/ (the Shopfront guide; its Express deep dive is the express-*.html sections, the express-flow diagram, and the TOPICS entry and Topics part in guide_config.py), source-postgresql/ (the PostgreSQL topic guide), and source-hub/ (the hub). The build writes shopfront-guide/, shopfront-postgresql-guide/ and shopfront-guides/ there, and index.html redirects to the hub. After changing the engine or the demo source, regenerate everything and commit the results:

docs/demo/make-demo.sh                   # build, run QA, recapture docs/images/*.png
docs/demo/make-demo.sh --no-screenshots  # build and QA only

CI fails if anything under docs/demo/ is out of date. The build pins the hub's dates with SOURCE_DATE_EPOCH, so rebuilding without changes leaves the files untouched.

Releasing

Bump version in .claude-plugin/plugin.json when you change the skill or agents, and move the Unreleased notes in CHANGELOG.md under the new version. Users pick it up with /plugin marketplace update, and the version badge above updates automatically.

License

MIT. The guides you generate document your own internal systems, so keep them internal (see references/sharing.md).