codebase-to-skill

Turn any software repository into a skill-style knowledge pack for fast onboarding and confident changes (Claude Code or pi).

This is the codebase analogue of “book-to-skill”: instead of a PDF/EPUB, the input is a repo (local folder or a cloned checkout). The output is a structured skill that summarizes architecture and provides on-demand deep dives into modules and key flows.

What it generates

Running (inside an agent that supports skills):

/codebase-to-skill /path/to/repo [skill-slug]

creates a skill directory at (depending on agent):

# Claude Code
~/.claude/skills/<slug>/

# pi (common setup)
~/.agents/skills/<slug>/
  SKILL.md
  modules/
  flows/
  contracts/
  glossary.md
  patterns.md
  playbook.md

Install

Claude Code

mkdir -p ~/.claude/skills/codebase-to-skill/scripts

curl -o ~/.claude/skills/codebase-to-skill/SKILL.md \
  https://raw.githubusercontent.com/<YOUR_GH_USER>/codebase-to-skill/main/SKILL.md

curl -o ~/.claude/skills/codebase-to-skill/scripts/extract_repo.py \
  https://raw.githubusercontent.com/<YOUR_GH_USER>/codebase-to-skill/main/scripts/extract_repo.py

pi

mkdir -p ~/.agents/skills/codebase-to-skill/scripts

curl -o ~/.agents/skills/codebase-to-skill/SKILL.md \
  https://raw.githubusercontent.com/<YOUR_GH_USER>/codebase-to-skill/main/SKILL.md

curl -o ~/.agents/skills/codebase-to-skill/scripts/extract_repo.py \
  https://raw.githubusercontent.com/<YOUR_GH_USER>/codebase-to-skill/main/scripts/extract_repo.py

Note: you may also want to edit SKILL.md to point to ~/.agents/skills/... paths depending on your pi setup.

How it works (high level)

1. scripts/extract_repo.py inventories the repo (respects .gitignore when run inside a git repo).
2. The agent uses those facts + targeted reads to generate compact architecture notes and on-demand module/flow files.

Optional repo config

Create .codebase-to-skill.toml in the target repo:

[codebase_to_skill]
exclude_globs = ["docs/**", "**/generated/**"]
skip_dirs = [".direnv"]
max_files = 200000
max_tree_lines = 1200
max_bytes_per_file = 2000000

License

MIT