SkillSmith

Convert GitHub repositories and documentation websites into Agent Skills — structured knowledge documents that teach AI agents how to use a library or API effectively.

How it works

SkillSmith runs a 5-phase pipeline designed to handle large documentation sources without hitting LLM output limits:

Ingest (GitHub API / BFS crawler)
  ↓
Phase 1  Map     — parallel LLM summarization of each page
                   reference pages keep original content (no compression)
  ↓
Phase 2  Reduce  — merge summaries into a unified overview
  ↓
Phase 3  Plan    — decide which files to generate (SKILL.md sections, references/, scripts/)
  ↓
Phase 4  Fan-out — Batch A: reference files (parallel, full token budget each)
                   Batch B: SKILL.md body + scripts (parallel, body knows what refs exist)
  ↓
Phase 5  Assemble → write to disk

Each generated file gets its own full LLM output budget instead of all files competing for a single 8k-token response.

Installation

git clone https://github.com/your-org/skillsmith
cd skillsmith
uv sync

Requires Python 3.11+ and an Anthropic API key (or any OpenAI-compatible endpoint).

Usage

Interactive chat

uv run skillsmith

SkillSmith — Convert repos and docs into Agent Skills
You: Create a skill from https://github.com/anthropics/anthropic-sdk-python
You: Generate a skill from https://docs.pydantic.dev --output ./my-skills

Single message

# From a GitHub repo
uv run skillsmith -m "Create a skill from https://github.com/anthropics/anthropic-sdk-python"

# From a documentation site
uv run skillsmith -m "Generate a skill from https://docs.pydantic.dev" --output ./skills/

# With a custom name
uv run skillsmith -m "Create a skill named fastapi-auth from https://fastapi.tiangolo.com/tutorial/security/"

MCP server

Expose SkillSmith as an MCP tool so other agents (Claude Code, Cursor, etc.) can generate skills on demand:

uv run skillsmith serve --port 8000

Available MCP tools:

• create_skill_from_github(url, output_dir, name?) — generate from a GitHub repo
• create_skill_from_docs(url, output_dir, depth?, name?) — generate from a docs site
• list_skills(directory) — list existing skill folders

Configuration

Priority: CLI flags > environment variables > ~/.skillsmith/config.toml

~/.skillsmith/config.toml

api_key = "sk-ant-..."
model   = "claude-opus-4-5"
output_dir = "~/skills"

OpenAI-compatible endpoints

Set base_url to use any OpenAI-compatible API (Ollama, vLLM, OpenRouter, etc.):

SKILLSMITH_BASE_URL=https://api.openai.com/v1 \
SKILLSMITH_MODEL=gpt-4o \
uv run skillsmith -m "Create a skill from https://github.com/openai/openai-python"

Output structure

Each skill is written as a folder following the Agent Skills specification:

skills/
└── anthropic-sdk/
    ├── SKILL.md              # Frontmatter + instructions (<500 lines)
    ├── references/
    │   ├── api-reference.md  # Loaded on demand by the agent
    │   └── error-codes.md
    └── scripts/
        ├── quickstart.py     # Self-contained, runnable
        └── streaming.py

SKILL.md includes cross-references to companion files:

See [API Reference](references/api-reference.md) for full method signatures.
Run scripts/quickstart.py to get started.

Project structure

src/skillsmith/
├── main.py           # CLI entry point (typer)
├── config.py         # Config loading + LLM factory
├── models.py         # Pydantic: Page, ContentBundle, SkillDraft
├── generator.py      # 5-phase Map-Reduce pipeline
├── writer.py         # Write SkillDraft to disk
├── chat.py           # Terminal UI (rich + prompt_toolkit)
├── mcp_server.py     # MCP server (fastmcp)
├── agent/
│   ├── graph.py      # LangGraph StateGraph
│   └── tools.py      # @tool wrappers for agent use
└── ingestors/
    ├── github.py     # GitHub REST API (README + docs/ + root .md files)
    └── docs.py       # BFS crawler (httpx + BeautifulSoup + markdownify)