Metadata-Version: 2.4
Name: agentskillsmith
Version: 2.0.0
Summary: Convert GitHub repos and documentation websites into Agent Skills
Project-URL: Homepage, https://github.com/koltenluca/SkillSmith
Project-URL: Repository, https://github.com/koltenluca/SkillSmith
Project-URL: Issues, https://github.com/koltenluca/SkillSmith/issues
Author: SkillSmith
License: MIT
Keywords: agent,ai,langchain,langgraph,llm,skills
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: fastmcp>=2.0
Requires-Dist: httpx>=0.27
Requires-Dist: langchain-anthropic>=0.3
Requires-Dist: langchain-google-genai>=4.2.1
Requires-Dist: langchain-openai>=0.2
Requires-Dist: langchain>=0.3
Requires-Dist: langgraph>=0.2
Requires-Dist: markdownify>=0.13
Requires-Dist: prompt-toolkit>=3.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# SkillSmith

Convert GitHub repositories and documentation websites into [Agent Skills](https://agentskills.io/specification) — 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

```bash
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

```bash
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

```bash
# 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:

```bash
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`

| CLI flag | Env var | Config key | Default |
|---|---|---|---|
| `--api-key` | `SKILLSMITH_API_KEY` | `api_key` | (Anthropic default) |
| `--base-url` | `SKILLSMITH_BASE_URL` | `base_url` | `""` (use Anthropic) |
| `--model` | `SKILLSMITH_MODEL` | `model` | `claude-opus-4-5` |
| `--output` | `SKILLSMITH_OUTPUT_DIR` | `output_dir` | `~/skills` |

### `~/.skillsmith/config.toml`

```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.):

```bash
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](https://agentskills.io/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:

```markdown
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)
```
