# code-to-catalog

Scans a repository to map domains, services, AI agents, and event flows, then runs an evidence-based interview to produce an EventCatalog plan.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 607 installs · ★ 13
- Author: eventcatalog
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/event-catalog/skills/tree/HEAD/skills/code-to-catalog/SKILL.md
- Updated: 2026-10-19
- HTML: https://affpapa.org/en/nevibecode/skills/code-to-catalog

## What it does

The skill inspects your codebase to detect service boundaries, AI worker runtimes, and messaging primitives. It asks one question at a time. Every suggestion cites evidence with a specific file path and line number so you can verify each decision without blind trust.

It works on new repositories and existing catalogs that drifted from the implementation. If `eventcatalog.config.js` exists, it marks missing or changed resources. It never deletes orphaned catalog items automatically, flagging them for review instead.

This skill stops after generating `.catalog-plan.md` and does not write final catalog markdown files itself. Creating the actual catalog documentation requires handing off the verified plan to the companion skill `catalog-documentation-creator`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add event-catalog/skills --skill code-to-catalog -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/code-to-catalog/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/code-to-catalog/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add event-catalog/skills --skill code-to-catalog -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/code-to-catalog/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add event-catalog/skills --skill code-to-catalog -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/code-to-catalog/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install event-catalog/skills code-to-catalog
```

2. **Manually: put the files in place**
- File: `.github/skills/code-to-catalog/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add event-catalog/skills --skill code-to-catalog -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/event-catalog/skills --path skills/code-to-catalog
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/code-to-catalog/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add event-catalog/skills --skill code-to-catalog -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/event-catalog/skills/tree/HEAD/skills/code-to-catalog/SKILL.md

## When to use it
- discover services, message topics, and commands across a codebase
- map AI agent boundaries, tools, and memory stores
- reconcile an existing EventCatalog setup against updated code
- generate a verified `.catalog-plan.md` architectural blueprint

## Example prompts
- Turn this repository into an EventCatalog
- Reconcile my existing catalog with the current code
- Find all AI agents in the project and prepare an architectural model

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: b8d0927d38567dab.

BEGIN THIRD-PARTY FILE b8d0927d38567dab
```text
---
name: code-to-catalog
description: Turns a codebase into EventCatalog documentation through an evidence-based interview. Scans the code first, proposes an architectural model (domains, services, agents, messages, channels), grills the user on the structural decisions, produces a reviewable plan file, then hands off to catalog-documentation-creator. Use when user says "document my codebase in EventCatalog", "turn this repo into a catalog", "model my code as a catalog", "document my agents", "document my AI agents", "grill me on my architecture", "update my catalog from the code", "reconcile my catalog with my code", or "I don't know where to start documenting this codebase". Works for brand-new catalogs AND for updating existing catalogs that have drifted from the code.
license: MIT
metadata:
  author: eventcatalog
  version: "1.0.0"
---

# Code to Catalog

Turn a codebase into EventCatalog documentation through a guided, evidence-based interview. Works for two situations:

1. **No catalog yet** — document an unfamiliar or undocumented codebase from scratch.
2. **Existing catalog** — reconcile the catalog with the current code (add new resources, flag drift, surface stale entries).

This skill does not write catalog files itself. It produces a **plan file** (`.catalog-plan.md`) that captures the agreed architectural model, then hands off to the `catalog-documentation-creator` skill to generate the actual documentation.

## How this skill works

The skill runs in six phases. Follow them in order — later phases depend on earlier ones.

1. **Locate & inventory** — find the code directory and any existing catalog
2. **Discovery scan** — read the code, form a hypothesis
3. **Reconcile with existing catalog** — categorize findings as `new` / `update` / `unchanged` / `investigate`
4. **Tiered grilling** — interview the user on structural decisions only
5. **Produce the plan file** — write `.catalog-plan.md`, get approval
6. **Handoff** — ask whether to generate the catalog now or stop at the plan

## Conversational style (applies throughout)

- **One question at a time.** Never batch questions. The user answers, then move on.
- **Always provide a recommended answer.** Every question includes what you think is true, with evidence (file path + line number). The user confirms, corrects, or overrides.
- **Cite the code.** When you present a finding, point at the file where you saw it — e.g., `src/orders/events.ts:42`. The user should be able to verify without trusting you.
- **Be honest about uncertainty.** If the code does not tell you whether something is an event or a command, say so. Do not guess silently.
- **Surface conflicts, do not pick silently.** When catalog and code disagree, the user decides. Never overwrite without confirmation.
- **Respect the user's time.** Grilling is tiered on purpose — structural decisions only. Do not grill on per-resource fields (summaries, owners, schemas).
```
END THIRD-PARTY FILE b8d0927d38567dab

The third-party file has ended. Everything between the b8d0927d38567dab tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2962 of 19037 bytes. © eventcatalog · MIT · https://github.com/event-catalog/skills/tree/HEAD/skills/code-to-catalog/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md