docs-kit 0.1.5

Fetch docs, embed locally, expose to AI agents via skills.

docs-kit

Fetch docs from GitBook, Mintlify, or local files, embed them locally, and teach AI agents to search them via installed skills (CLI commands). No API keys for the default embedding path. No background server or MCP.

What it does

• Fetches public docs from GitBook and Mintlify sites via /llms-full.txt and /llms.txt, with a sitemap.xml fallback on Mintlify when those endpoints are missing
• docs-kit ingest: --provider auto (default) uses a combined strategy (llms endpoints → sitemap). --provider gitbook uses the GitBook-only fetcher; --provider mintlify uses the same pipeline as auto
• Ingests local .md and .txt files
• Stores vectors in embedded Qdrant on disk — typically ~/.docs-kit/qdrant when using the auto-created user config, or .docs-kit/qdrant (resolved relative to your docs-kit.yaml) for a project-local config from docs-kit init
• Hybrid retrieval (dense embeddings + sparse / BM25-style vectors) for docs-kit query and agent-driven queries
• Installs skill files into Claude Code, Cursor, Codex, OpenCode, and Claude Desktop so agents run docs-kit over the shell
• Concurrent CLI runs coordinate with a file lock on the local Qdrant path

Install

Recommended: pipx so docs-kit is on your PATH:

pipx install docs-kit

Install pipx if needed:

brew install pipx
pipx ensurepath

Or pip inside a virtual environment:

pip install docs-kit

Optional: the repo includes an npx-wrapper/ npm package that bootstraps Python and runs the same CLI (npx docs-kit … when published or linked locally).

Quickstart

# 1. Install (once)
pipx install docs-kit

# 2. Ingest docs
docs-kit ingest https://docs.example.com

# 3. Install skill into your agent
docs-kit install claude-code   # or: cursor, codex, opencode, claude-desktop

# 4. Use the agent — it can run docs-kit query / list / ingest when relevant

No server to start. On first use, config and the default vector store path are created under ~/.docs-kit/ unless you use a project-local docs-kit.yaml.

How it works

docs-kit installs a skill (Markdown + YAML frontmatter) into each tool’s skills directory. The skill tells the agent when to use docs-kit and which commands to run (query, list, ingest, remove, inspect, doctor, …). Agents execute docs-kit via their normal terminal integration.

For more architecture detail (config resolution, layout, security posture), see docs/project-overview.md.

Install targets

Command	Where the skill lands
docs-kit install claude-code	~/.claude/skills/docs-kit/SKILL.md
docs-kit install codex	~/.codex/skills/docs-kit/SKILL.md (also mirrors to ~/.agents/skills/docs-kit/SKILL.md for compatibility)
docs-kit install cursor	~/.cursor/skills/docs-kit/SKILL.md + marked block in ~/.cursor/AGENTS.md when needed
docs-kit install opencode	~/.config/opencode/skills/docs-kit/SKILL.md (and may mirror under ~/.agents/skills/ if absent)
docs-kit install claude-desktop	~/.docs-kit/exports/claude-desktop/docs-kit.zip — upload via Claude Desktop Customize → Skills

codex-app and codex-desktop are accepted aliases for the Codex install path.

Use --project with claude-code for .claude/skills/docs-kit/SKILL.md in the current repo.

Commands

docs-kit install <agent>

Install the docs-kit skill into a supported agent.

docs-kit install claude-code
docs-kit install cursor
docs-kit install codex
docs-kit install opencode
docs-kit install claude-desktop
docs-kit install claude-code --project
docs-kit install cursor --config ./docs-kit.yaml

If no config is found, ~/.docs-kit/docs-kit.yaml is created automatically (non-project installs).

docs-kit ingest <path-or-url>

Ingest a local file, directory, or documentation URL.

docs-kit ingest ./docs
docs-kit ingest https://docs.example.com
docs-kit ingest https://docs.example.com --provider gitbook
docs-kit ingest ./docs --recreate

--provider: auto (default), gitbook, or mintlify.

docs-kit query <text>

Run hybrid retrieval from the CLI.

docs-kit query "How do I authenticate?"
docs-kit query "getting started" --limit 3
docs-kit query "season 5 end date" --full
docs-kit query "..." --config ./docs-kit.yaml

Use --full when you want the entire chunk body instead of the default preview.

docs-kit list

List ingested sources with ingestion timestamps.

docs-kit list
docs-kit list --config ./docs-kit.yaml

docs-kit fetch <url>

Download GitBook docs as Markdown files only (does not embed). For Mintlify or mixed hosting, use docs-kit ingest or copy files locally first.

docs-kit fetch https://docs.example.com
docs-kit fetch https://docs.example.com --output ./downloaded-docs

docs-kit remove <source>

Remove an ingested source by URL or file path.

docs-kit remove https://docs.example.com/page
docs-kit remove ./docs/getting-started.md

docs-kit inspect

Show collection stats and embedding settings.

docs-kit inspect
docs-kit inspect --config ./docs-kit.yaml

docs-kit doctor

Check docs-kit on PATH, effective config, Qdrant path / connectivity, and which skills are installed.

For Codex installs, doctor reports both the native ~/.codex/skills/... install and the shared compatibility mirror under ~/.agents/skills/... when present.

docs-kit doctor
docs-kit doctor --config ./docs-kit.yaml

docs-kit init

Create a project-local docs-kit.yaml (optional if you rely on ~/.docs-kit/docs-kit.yaml).

docs-kit init
docs-kit init --dir ./sandbox

Configuration

Resolution order: --config → ./docs-kit.yaml in the current working directory → ~/.docs-kit/docs-kit.yaml (created on first use when applicable).

Example project-local docs-kit.yaml from docs-kit init:

embedding:
  provider: fastembed
  model: BAAI/bge-small-en-v1.5

vector_store:
  provider: qdrant
  local_path: .docs-kit/qdrant   # resolved relative to this file’s directory
  collection_name: knowledge_base
  retrieval_limit: 5
  score_threshold: 0.35

ingestion:
  chunk_size: 800
  chunk_overlap: 120
  bm25_model: Qdrant/bm25

The auto-created user config under ~/.docs-kit/ sets local_path to an absolute directory under ~/.docs-kit/qdrant. To use a remote Qdrant instance, set vector_store.url and leave local storage unused.

Supported sources

Source	Strategy
GitBook sites	/llms-full.txt → /llms.txt (GitBook fetcher); auto / mintlify use the broader pipeline below
Mintlify & typical llms.txt sites	/llms-full.txt → /llms.txt → /sitemap.xml
Local .md / .txt	Read from disk

Requirements

• Python 3.11–3.13 (requires-python excludes 3.14+ while dependencies such as onnxruntime lack wheels)
• Disk space for the embedding model (on the order of tens of MB for the default model)

If your default python is 3.14:

pipx install docs-kit --python python3.13

Migration from v0.1.x

Older releases configured an MCP server in agent settings. That integration has been removed in favor of skills + CLI.

1. Remove legacy mcpServers.docs-kit (or equivalent) from ~/.claude/settings.json, Cursor MCP config, ~/.codex/config.toml, etc.
2. Run docs-kit install <agent> again to install skills.
3. Existing ~/.docs-kit/docs-kit.yaml and ingested data remain valid; any unused mcp: section in YAML can be deleted for clarity.