Skip to main content
plugin

reef — Claude Code plugin: what it does, how to install

reef generates an interlinked, local-first Markdown wiki from your services, schemas, and APIs through automated passes and guided Q&A.

Apache-2.0 ★ 6 updated 2026-10-08

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add anthropics/claude-plugins-community
/plugin install reef@claude-community
Open on GitHub

What reef does

Reef reads your source code to map out databases, REST, gRPC, or GraphQL endpoints. It stores documentation locally as plain Markdown files with YAML frontmatter formatted for Obsidian. Running /reef:init scaffolds the workspace and kicks off draft discovery alongside ERD extraction.

The plugin works in distinct passes. /reef:scuba engages in Socratic questioning to capture rationale and service ownership that code cannot explain on its own. For fragile core paths, /reef:deep performs line-by-line tracing with source citations. Unresolved gaps land in .reef/questions-for-owner.md via /reef:ask.

The workflow targets ecosystems of 3 to 15 interconnected repositories. Standalone mobile apps without backends, embedded firmware, or machine learning notebooks lack the service boundaries and schemas Reef relies on.

What it helps with

  • Extract API contracts and database schemas into interlinked documentation
  • Compile a local-first Obsidian wiki from multiple microservice repositories
  • Capture architectural intent and ownership through guided Socratic questions
  • Provide domain context files for Claude Code, Cursor, or Copilot

Example prompts for the agent

  • /reef:init to bootstrap documentation across local service repos
  • /reef:scuba to answer guided questions about architecture decisions
  • /reef:ask to generate a prioritized list of unresolved codebase gaps

How to install reef

Plugin marketplace

/plugin marketplace add anthropics/claude-plugins-community
/plugin install reef@claude-community

Step by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own

Questions about reef

How to install reef in Claude Code?

Run /plugin marketplace add anthropics/claude-plugins-community and then /plugin install reef@claude-community.

What kind of codebases does reef support?

It works best on multi-repo ecosystems, microservices, and modular monoliths with databases and API interfaces. Codebases without backend schemas or service boundaries, such as game engines or embedded firmware, are not supported.

Can the generated wiki be used with other dev tools?

The output consists of local Markdown files with YAML frontmatter. You can open them in Obsidian or point Claude Code, Cursor, and Copilot to the folder for domain context.

Source text

SKILL.md · Apache-2.0
# Reef

Most codebase knowledge lives in someone's head, or gets re-derived from scratch every time someone asks a question. Reef takes a different approach: it builds a persistent, structured wiki from your source code — one that compounds over time instead of being rediscovered on every query.

Reef is a Claude Code plugin. It reads source code, asks the right questions, and produces interlinked markdown artifacts with YAML frontmatter, source citations, and honest gap tracking. The AI does the reading and the bookkeeping. You bring the domain knowledge and decide what matters. Output is Obsidian-native, local-first, plain markdown.

## Built For

Reef is designed for **codebases that have services, data, and interfaces**. If your code has APIs (REST, gRPC, GraphQL), persistent data (any database or ORM), and components that talk to each other — Reef will produce rich, interlinked artifacts.

It works well for: microservices, monoliths with modules, full-stack apps, data pipelines, infrastructure-as-code, DevOps toolchains, and anything in between.

It is not the right tool for: native mobile apps with no backend, game engines, embedded firmware, or ML training notebooks. These don't have the data schemas, API surfaces, or service boundaries that Reef is built to document.

## Guide

For a full step-by-step walkthrough of the workflow (init → scuba → deep → update), see **[docs/guide.md](docs/guide.md)**.

## Quick Start

```
/plugin marketplace add eunji-jessi-jung/reef
/plugin install reef@eunji-jessi-jung-reef
```

Then, in any project directory:

```
/reef:init        # Set up the reef, then auto-runs snorkel + source in parallel:
                  #   snorkel — auto-discover 3-6 draft artifacts
                  #   source  — extract full API specs and ERDs
/reef:scuba       # Deepen drafts through guided Socratic questioning
```

## Skills

| Skill | Description |
|-------|-------------|
| `/reef:init` | Bootstrap a new reef — scope, scaffold, index, seed questions |
| `/reef:snorkel` | Auto-discovery surface pass, 3-6 draft artifacts, no questions asked |
| `/reef:source` | Extract full API specs and ERDs with tiered protocol + recipe caching |
| `/reef:scuba` | Socratic deepening through guided question-and-answer |
| `/reef:deep` | Exhaustive line-by-line tracing of critical areas |
| `/reef:artifact` | Explore a topic, capture knowledge, or update an artifact |
| `/reef:update` | Pull sources, detect changes, generate update report for review |
| `/reef:lint` | Lint artifacts for format and structural errors, with auto-fix |
| `/reef:health` | Read-only validation and freshness report |
| `/reef:feed` | Scan for new context files and connect them to the reef |
| `/reef:test` | Test whether the reef answers your real questions |
| `/reef:ask` | Collect the reef's open gaps into a ranked question bank for the owner |

## When to Use Each Depth

**Snorkel** — First contact with a codebase. No questions, no input. Produces draft artifacts with honest `known_unknowns`. Also useful when adding a new source to an existing reef.

**Source** — After snorkel, before scuba. Extracts complete API specs and entity-relationship diagrams from your source repos. Tries copying existing specs first, then runtime extraction, then code reading as fallback. Caches successful recipes so repeat runs are fast.

**Scuba** — You have drafts, full API/ERD specs, and domain knowledge. The AI reads code and asks you things code alone can't answer: why decisions were made, who owns what, what breaks in practice. This is where most real knowledge gets captured.

**Deep** — Critical systems where shallow reading misses real behavior. Line-by-line tracing, 5+ Key Facts per artifact with precise citations. Reserve for areas where getting it wrong has consequences.

**Ask** — Whenever the reef was built without a domain expert on hand. Scuba's default posture assumes someone is beside you who already knows the answers. Often nobody is: the authors left, the run was unattended, or you arrived yesterday. `/reef:ask` resolves the gaps the sources can still settle, then deposits the rest as a ranked question bank — each entry saying what it would unblock and what was already checked, so the owner never repeats work the agent already did.

## I Built a Reef — Now What?

A reef is a living knowledge base. Once scuba completes (even partially), you can:

- **Feed it to dev agents** — point Claude Code, Cursor, or Copilot at the reef directory as context so they understand your domain, not just your syntax
- **Onboard teammates** — open in Obsidian, explore the knowledge graph, ramp up without scheduling walkthrough meetings
- **Export as docs** — artifacts are structured markdown with frontmatter; copy into Confluence, Notion, or a static site
- **Audit and review** — `/reef:health` for coverage gaps, `/reef:test` to check if the reef answers your real questions
- **Keep it alive** — `/reef:update` after code changes; each update costs a fraction of the initial build

See [docs/guide.md](docs/guide.md) for the full workflow.

## Domain Boundaries

One reef covers one ecosystem — services that talk to each other. The sweet spot is **3-15 repos** that form a coherent domain. This is where Reef delivers the most value: complex enough that no one person holds the full picture, small enough that Reef can trace every cross-system connection.

- **1-2 repos:** Reef works, but the code might be its own best documentation. Consider whether you need it.
- **3-15 repos:** The goldilocks zone. Cross-service contracts, shared entities, and auth boundaries are where the real knowledge lives — and where it gets lost most often.
- **15+ repos:** Split into multiple reefs by team or domain. Each reef should cover services that directly interact. Services that don't talk to each other belong in separate reefs.

In a large org (hundreds of repos), the right unit is one reef per team or domain — not one reef for the whole org. A platform team's reef and a product team's reef are separate, each covering their own ecosystem.

## Two Question Banks

Reef keeps questions in two places, and they run in opposite directions.

**The discovery bank** (`.reef/questions.json`) — what you want the reef to answer. Seed questions during `/reef:init`. These are the north star. `/reef:test` evaluates whether the reef actually answers them. A reef that answers 8 of 10 questions is useful. A reef with beautiful artifacts that answers 2 of 10 is decorative.

**The owner bank** (`.reef/questions-for-owner.md`) — what the reef needs a human to answer. Built by `/reef:ask` from the `known_unknowns` the artifacts accumulated. Ranked by what each answer unblocks, and every entry states what was already checked so the owner does not repeat it. This is the reef asking, rather than being asked.

## Keeping It Alive

Knowledge bases die when the maintenance burden outgrows the value. Reef shifts that burden to the machine. `/reef:update` re-indexes sources, detects changes, and walks you through updating affected artifacts. `/reef:health` reports the state without modifying anything. Artifacts don't flip from good to bad — they age gradually. Run these after significant code changes.

## Nine Artifact Types

| Type | Prefix | Question it answers |
|------|--------|-------------------|
| System | SYS- | What does this service do? |
| Schema | SCH- | What does this data mean? |
| API | API- | What can I call? |
| Process | PROC- | What happens when...? |
| Decision | DEC- | Why was it built this way? |
| Glossary | GLOSSARY- | What does this term mean? |
| Contract | CON- | What do these systems agree on? |
| Risk | RISK- | What could go wrong? |
| Pattern | PAT- | What problem does this solve repeatedly? |

## Obsidian

Artifacts are wikilinked with `[[artifact-id]]` syntax — open the reef directory as an Obsidian vault to see the full graph of how everything connects. Enable Graph View and Dataview plugins for the best experience. The reef is plain markdown, so any markdown tool works.

## Adding Your Own Docs

Have architecture docs, design specs, or runbooks that aren't in the codebase? Drop them into `sources/raw/` in your reef directory. Scuba will pick them up when deepening artifacts — they're especially useful for answering questions that code alone can't.

## See It in Action

**[supabase-reef](https://github.com/eunji-jessi-jung/supabase-reef)** — a complete reef covering 5 Supabase repos (Go, Elixir, TypeScript, React) built by a PM with zero Supabase knowledge. Includes a [benchmark report](https://github.com/eunji-jessi-jung/supabase-reef/blob/main/reef-benchmark-report.md) testing whether the reef actually helps AI agents (28 runs, 2 models, 7 tasks, with honest caveats).

**[sellflow](https://github.com/eunji-jessi-jung/sellflow) + [sellflow-reef](https://github.com/eunji-jessi-jung/sellflow-reef)** — a fixture with a known answer, and the reef built over it. The fixture is a fictional company whose wiki, procedure and code all look authoritative and disagree; the brief has one correct answer and several of its load-bearing facts are absences. The reef is 80 artifacts, 532 recorded unknowns and 67 ranked questions for whoever owns the system, built with nobody available to ask — the case `/reef:ask` exists for. Clone them side by side to run `health`, `diff` and `update` on a reef someone else built, and read [ANSWER-KEY.md](https://github.com/eunji-jessi-jung/sellflow-reef/blob/main/ANSWER-KEY.md) to check the reef's claims against the fixture's own grading key.

## Author

**Eunji Jung** — Product Manager building tools for AI-assisted software engineering.

- [LinkedIn](https://www.linkedin.com/in/eunji-jessi-jung/)
- Questions or feedback? [Open an issue](https://github.com/eunji-jessi-jung/reef/issues)

© eunji-jessi-jung · Apache-2.0 · eunji-jessi-jung/reef

Similar plugins

All plugins for Writing and docs →

Project sponsors

Companies that keep this analytics open