explain-project

Reconstruct codebase understanding through repo reading and one-question interviews.

1|Updated Apr 24, 2026

Search Tags:#architecture #project documentation #knowledge capture #build-in-public #code comprehension #interview-based reasoning #README backfill

Ready to run

npx skills add https://github.com/shawnpetros/claude-skills --skill explain-project-shawnpetros

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: explain-project
Source: https://github.com/shawnpetros/claude-skills/tree/main/explain-project
Command: npx skills add https://github.com/shawnpetros/claude-skills --skill explain-project-shawnpetros

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

It helps you rebuild an accurate understanding of a codebase you built (or inherited) when the README and code comments are incomplete, so you can explain it clearly without guessing.

Core Features & Use Cases

Repo-first comprehension: Reads the repository (README, manifest, entry points, recent history, and optional existing context) to draft what the project is and how it’s structured.
Gap interview loop: Asks one targeted question at a time only where the code cannot reveal intent, tradeoffs, fragility, or what changed your thinking.
4-section artifact delivery: Produces a concrete explanation in four parts: What is this / Why this approach / What would break / What I learned, suitable for README/CLAUDE.md/build-in-public.

Quick Start

Use /explain-project to generate a 4-section explanation artifact for the project in your workspace by reading the repo first and then asking targeted one-question-at-a-time follow-ups.

Frequently Asked Questions about explain-project

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

FAQPage Schema

How do I backfill stale project documentation when I forgot my codebase architecture?▼

To backfill stale project documentation, you can read the repository structure and conduct a targeted interview to capture intent, producing a concrete four-section explanation artifact covering what the project is, why, fragility, and lessons learned.

What is the best way to generate build-in-public notes from an existing codebase?▼

The best way to generate build-in-public notes is reconstructing honest project understanding by reading repo history and entry points, then asking targeted questions to document tradeoffs and what changed your thinking without guessing details.

How do I write a README when the original developer left no code comments?▼

To write a README without code comments, use interview-based reasoning to extract intent where code is silent, filling a structured template with visible gaps rather than inventing architectural details or implementation rationale.

Can I document inherited code comprehension gaps without inventing project details?▼

Yes, you can document inherited codebase gaps safely by reading the repository first, then asking one targeted question at a time only where code cannot reveal intent, ensuring the output marks unknowns instead of fabricating explanations.

What should I do to prepare a codebase for a controlled interview-based reasoning session?▼

Preparing for interview-based reasoning requires a repo read pass covering the README, manifest, entry points, and recent history to draft initial project structure before asking targeted follow-up questions.