---
name: walnut-register-repo
description: >-
  Deep-explore current codebase and register it as a Walnut repository.
  Produces a rich profile: what the project does, architecture overview,
  key components, tech stack, and common workflows.
  Use when user says "register repo", "add this repo", "/walnut-register-repo",
  or wants to create a Walnut repository profile for the current project.
---

# Register Repository

Explore this codebase and produce a rich, structured repository profile.

## Goal

Create a YAML file at `~/.open-walnut/repositories/{slug}.yaml` that genuinely captures what this project is, how it works, and how to work with it. Someone reading this profile should understand the project without opening a single file.

## How to explore

Start with a quick broad scan — directory structure, README, package manifest — to get the lay of the land. Based on what you find, decide what needs deeper investigation. Use sub-agents for parallel deep dives into areas you identify as important.

You decide the exploration strategy. A React SPA needs different investigation than a microservice or a CLI tool. Go where the interesting stuff is.

**Quality bar**: "A web application built with React" is useless. "Real-time collaborative document editor with CRDTs for conflict resolution, React frontend with ProseMirror, and WebSocket sync server" is what we want.

## Output Format

Write the YAML to `~/.open-walnut/repositories/{slug}.yaml`:

```yaml
name: Project Name
description: >-
  1-3 sentences. Specific about what it does, not generic.
  This shows in listings and the main agent's system prompt.
tech_stack: [Lang, Framework, DB, ...]
hosts:
  local:
    path: /absolute/path   # use current working directory

overview: |
  ## What
  What this project does — be specific.

  ## Why
  Why it exists — what problem, who uses it.

  ## How
  High-level how it works — the 30-second explanation.

architecture: |
  Major components, how they connect, key directories.
  An agent reading this should understand the codebase layout.

common_commands: |
  The commands a new developer needs on day one.
```

**Required**: name, description, hosts (at least one with path)
**Important**: overview and architecture — these get injected into every Claude Code session working on this repo. Make them genuinely useful.

The complete YAML format spec with examples is in `references/yaml-format.md` next to this SKILL.md file.

## After writing

Validate with the script next to this SKILL.md:
```
python3 {this_skill_dir}/scripts/validate-repo.py ~/.open-walnut/repositories/{slug}.yaml
```
(Replace `{this_skill_dir}` with the directory containing this SKILL.md file.)

Show the user the result. Don't ask a checklist of questions — just show it and ask if anything needs adjustment.