Repo To Skill

Repo-to-Skill: Convert a Repository into a Claude Code Skill

Purpose

This skill encodes the complete workflow for transforming a GitHub repository (or local codebase) into a well-structured Claude Code skill. It guides you through cloning, exploring, extracting key information, and assembling a skill with proper progressive disclosure — a concise SKILL.md entry point backed by detailed reference files.

When to Use

Activate when the user:

• Provides a GitHub URL and asks to create a skill from it
• Points to a local repository path and wants it converted to a skill
• Says "make a skill from this repo/library/tool"
• Wants to document a codebase as a reusable skill

Workflow Overview

1. Acquire repo  →  2. Explore broadly  →  3. Collect key info  →  4. Design structure  →  5. Write SKILL.md + references

Phase 1: Acquire the Repository

From GitHub URL

# Clone to a working directory
git clone <github-url> /tmp/skill-source-repo
# or clone to a user-specified path

If the user provides just a repo name (e.g., "mne-tools/mne-python"), construct the URL:

git clone https://github.com/<owner>/<repo>.git /tmp/skill-source-repo

From Local Path

If the user provides a local path (e.g., /srv/repos/my-library), use it directly. Verify it exists before proceeding.

Already Available

Check if the repo is already cloned locally before downloading again.

Phase 2: Explore the Repository

This is the most important phase. Explore broadly and deeply — the quality of the skill depends on how well you understand the repo. Use parallel subagents when possible to speed up exploration.

2.1 Top-Level Orientation

Read these files first (if they exist):

• README.md / README.rst — project overview, installation, quick start
• CHANGELOG.md / CHANGES.rst / HISTORY.md — recent API changes
• pyproject.toml / setup.py / setup.cfg / package.json — dependencies, version
• CONTRIBUTING.md — project conventions
• LICENSE — license type

Then list the top-level directory structure to understand the project layout.

2.2 Core Source Code

Identify the main source directory (often src/, lib/, or the package name itself). Then:

1. Read __init__.py (or equivalent entry point) to find all exported modules/classes/functions
2. List all submodules/subdirectories
3. For each major submodule, read its __init__.py to get the public API
4. Read key implementation files for important classes/functions — focus on docstrings and signatures, not internal logic

2.3 Documentation

Look for documentation in these common locations:

• docs/ or doc/ directory
• examples/ directory — working code examples are gold
• tutorials/ directory — step-by-step guides
• API reference docs (often generated, but source .rst or .md files are useful)
• Jupyter notebooks (.ipynb) in any directory

2.4 Examples and Tutorials

These are the most valuable resources for a skill. For each example/tutorial:

• Note what it demonstrates
• Extract the key code patterns
• Identify the recommended parameter values and best practices

2.5 Tests (Optional)

Skim test files to discover edge cases, expected behaviors, and usage patterns that aren't in the docs.

Exploration Strategy

Use the Agent tool with subagent_type=Explore for broad exploration, or launch multiple parallel subagents to cover different areas simultaneously:

Agent 1: Explore top-level structure + README + core __init__.py files
Agent 2: Explore tutorials/ and examples/ directories, read representative files
Agent 3: Explore docs/ for API reference, read key module documentation

The goal is to collect:

• Complete list of public API (classes, functions, constants)
• Recommended usage patterns and pipelines
• Parameter defaults and recommended values
• Common pitfalls and gotchas
• Code examples for each major feature

Phase 3: Design the Skill Structure

Determine Scope

Based on exploration, decide:

• What is the skill's primary purpose? (e.g., "guide users through X analysis pipeline")
• What are the major topic areas? (these become reference files)
• What belongs in the main SKILL.md vs. references?

Progressive Disclosure Architecture

skill-name/
├── SKILL.md              (< 500 lines — overview, pipeline, quick reference)
└── references/
    ├── topic-a.md        (detailed API + examples for topic A)
    ├── topic-b.md        (detailed API + examples for topic B)
    ├── topic-c.md        (detailed API + examples for topic C)
    └── ...

Rules of thumb:

• SKILL.md: Pipeline overview, core concepts, quick-start code, common pitfalls, reference table pointing to detail files
• Each reference file: One major topic, complete API listing, detailed code examples, parameter tables
• Keep each file under 300 lines for readability; split if larger
• Include a "Reference Files" table in SKILL.md so the model knows when to read each file