| 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:
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
overview: |
## What
What this project does — be specific.
Why it exists — what problem, who uses it.
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.
