doc2skill

"Why create skills with AI when you already have online documentation? Use the #1 rule of programming: reuse what already exists."

Turn any package's documentation into a ready-to-use agent skill — no prompt engineering, no copy-pasting.

Point it at a crate, a NuGet package, an npm module, or any llms.txt URL — and get a clean Markdown skill file your AI agent can actually read.

---

Table of contents

• Overview
• Install
• The three-phase workflow
  • 1 · Import — fetch documentation and generate a skill
  • 2 · Review — inspect, treat warnings, or manually rewrite a skill
  • 3 · Refine — let an AI agent rewrite the skill for clarity
• Sources
• Output structure
• Configuration
• Counting tokens
• License

---

Overview

doc2skill is a CLI that turns package documentation into agent-ready skill files. It fetches docs from a registry (or any llms.txt URL), writes a structured SKILL.md with reference pages under references/, and gives you a small three-step workflow — Import › Review › Refine — to bring raw docs into a shape an AI agent can use.

---

Install

Cargo

cargo install doc2skill

mise

mise use github:Odonno/doc2skill

Tip: Add a short alias so you can type less every day:

alias d2s = doc2skill

---

The three-phase workflow

flowchart LR
    subgraph P1["1 · Import"]
        A1["Package docs<br/>registry / llms.txt"] --> A2["fetch over network"]
    end
    subgraph P2["2 · Review"]
        B1["SKILL.md +<br/>references/ + doc.skill"] --> B2["inspect &amp; count tokens"]
    end
    subgraph P3["3 · Refine"]
        C1["polished<br/>SKILL.md"] --> C2["pi rewrites for<br/>clarity &amp; usability"]
    end

    P1 -- "writes" --> P2
    P2 -- "hands off" --> P3

Loading

A tiny doc.skill file travels alongside each skill, recording where each phase stands (Pending → Done, or "skipped" when you bypass a step with --skip). Phases are independent — jump to any of them at any time.

1 · Import

↑ back to top

Fetch documentation for a package and write a skill. This is the only phase that hits the network.

Import a single package:

doc2skill import clap

name:        clap
version:     4.5.38
license:     MIT OR Apache-2.0
description: A simple to use, efficient, and full-featured Command Line Argument Parser
pages:       42 (41 references)

The skill lands in .agents/skills/clap/SKILL.md with its reference pages under .agents/skills/clap/references/.

Pin a version:

doc2skill import clap@4.4.0

Import several packages at once:

doc2skill import clap serde tokio

Pick the source explicitly (auto-detected from a project file otherwise — see Sources):

doc2skill import Newtonsoft.Json --source csharp
doc2skill import https://www.fastht.ml/docs/llms.txt --source llms-txt

Run interactively (no subcommand):

doc2skill

If a project file (Cargo.toml, *.csproj, package.json) is present, doc2skill lists your dependencies and lets you pick which to generate skills for. Otherwise it drops into an interactive search prompt.

The shortcut form doc2skill clap (no import subcommand) still works for single-package imports.

2 · Review

↑ back to top

Inspect what you imported before refining. Review prints a per-skill summary — version, token count, reference count — and flags oversized skills in red when they exceed 5 000 tokens.

Review every skill:

doc2skill review

clap
  version: 4.5.38
  tokens: 7421
  ⚠ skill content too large (7421 tokens > 5000)
  references: 41
serde
  version: 1.0.219
  tokens: 983
  references: 2

Review a single skill:

doc2skill review clap

Open a skill in your pager (zed --wait by default — see Configuration):

doc2skill review clap --open

Skip review without opening it (records reviewed = "skipped"):

doc2skill review clap --skip

3 · Refine

↑ back to top

Hand a skill to an AI agent (pi) to rewrite for clarity, completeness, and agent usability. Refine reads the current SKILL.md, sends it to the model configured in your config.toml, and atomically swaps in the polished version.

Refine a skill:

doc2skill refine clap

✓ Refined skill 'clap'

Override the model for one run:

doc2skill refine clap --model anthropic/claude-3.5-sonnet-latest

Skip refine without spawning the AI (records refined = "skipped"):

doc2skill refine clap --skip

Refine uses pi --print --model <model> --provider <provider> under the hood. Point it at a different binary with DOC2SKILL_PI_BIN.

---

Sources

A source is where doc2skill pulls documentation from. When a project file is found in the current directory, the source is auto-detected — no --source flag required.

Source	Auto-detection	Provider	References
Rust	Cargo.toml	crates.io	Traits, Structs, Enums, Functions, Constants, Macros
C#	*.csproj, Directory.Packages.props	NuGet	N/A
TypeScript	package.json	npm	Classes, Interfaces, Functions, Variables
llms.txt	URL ending in /llms.txt or /llms-full.txt	any URL	Linked pages (index form) or the whole body (llms-full.txt form)

llms.txt

The llms.txt source imports from any URL that follows the llms.txt convention:

• Index form — /llms.txt. The page is parsed into a description and a set of - [title](url) links; each link is fetched and stored as a reference page.
• Full-doc form — /llms-full.txt. Detected by URL suffix. A self-contained doc with no links to follow; the whole body is imported verbatim as a single skill with an empty references set.

doc2skill import https://example.com/docs/llms.txt
doc2skill import https://example.com/docs/llms-full.txt

The source is auto-detected from the URL suffix, so --source llms-txt is optional.

---

Output structure

Every imported skill is written under the configured output path (.agents/skills by default):

.agents/skills/
└── clap/
    ├── SKILL.md          # main skill page
    ├── doc.skill         # workflow state (reviewed / refined flags)
    └── references/
        ├── Arg.md
        ├── Command.md
        └── Parser.md

---

Configuration

User config lives at ~/.config/doc2skill/config.toml. It holds refine (model + provider) and editor (pager) settings.

[editor]
pager = "zed --wait"          # used by `review --open` (falls back to $PAGER)

[refine]
model = "anthropic/claude-3-5-haiku-latest"
provider = "github-copilot"   # any 'pi' provider name

Edit the config in $EDITOR

doc2skill config edit

Print the raw TOML (embedded default if no file exists)

doc2skill config show

---

Counting tokens

Token-counting lives in its own phase so you can size skills at any time, independent of Import/Review/Refine. Counts are highlighted in red when they exceed 5 000 tokens — a useful signal that a skill may be too large for some context windows.

Count all skills:

doc2skill count

.agents/skills
  clap
    SKILL.md - 1 247 tokens
    references
      Arg.md        - 3 819 tokens
      Command.md    - 8 504 tokens
      Parser.md     - 612 tokens
  serde
    SKILL.md - 983 tokens
    references
      Deserialize.md - 2 201 tokens
      Serialize.md   - 1 876 tokens

Count a single skill:

doc2skill count clap

Token counts require the tokens feature — if your build lacks it, recompile with --features tokens.

---

License

MIT