PromptGraph

Semantic skill router and marketplace for Claude Code, Claude Desktop, and OpenCode.

Instead of loading every .md skill into context, Claude calls pg_search and loads only the skill it needs — saving 20k+ tokens per session.

Features

• Semantic search — BGE-Small-EN embeddings (fastembed), local, no API key required
• Token savings — loads one skill on demand instead of all .md files (~20k+ tokens/session)
• Fast reindex — persistent embed cache makes re-indexing unchanged skills near-instant
• Flexible layouts — finds skills in nested subfolders and in .github/, .claude/, .opencode/ dot-folders (GitHub Copilot / agent conventions)
• Any local folder — pg add-dir <path> indexes a folder that isn't a default source
• Marketplace — browse and install community skill bundles via TUI or MCP tools
• Publishing — publish skills/bundles to the registry hands-off via GitHub CLI
• Multi-platform — verified on Claude Code, Claude Desktop & OpenCode; best-effort config for Cursor, Windsurf, Cline, Codex

Install

npm install -g promptgraph-mcp

Quick start

pg setup claude-code      # Claude Code
pg setup opencode         # OpenCode (writes opencode.json MCP config)
pg setup claude-desktop   # Claude Desktop
pg setup cursor           # Cursor

pg setup <platform> does three things:

1. Writes the MCP server config for that platform
2. Sets the skills directory for that platform (e.g. ~/.config/opencode/skills)
3. Runs a full index of your skills

Then restart your editor — the promptgraph MCP server will be available.

Supported platforms

Claude Code, Claude Desktop, and OpenCode are verified end-to-end. The others are best-effort — the MCP config path/format is implemented but untested, so pg setup warns before writing. If you run one, please report results.

| Platform | Status | Config written | Skills directory | |---|---|---|---| | claude-code | ✅ verified | ~/.claude/settings.json | ~/.claude/skills-store | | claude-desktop | ✅ verified | claude_desktop_config.json (OS-specific) | ~/.claude/skills-store | | opencode | ✅ verified | ~/.config/opencode/opencode.json | ~/.config/opencode/skills | | cursor | ⚠️ untested | ~/.cursor/mcp.json | ~/.cursor/skills | | windsurf | ⚠️ untested | ~/.codeium/windsurf/mcp_config.json | ~/.codeium/windsurf/skills | | cline | ⚠️ untested | ~/.vscode/mcp.json | ~/.vscode/skills | | codex | ⚠️ untested | ~/.codex/config.json | ~/.codex/skills |

CLI commands

# Setup & maintenance
pg setup <platform>             # Setup MCP config + skills dir for a platform
pg reindex                      # Re-index all skills (progress bar + ETA)
pg status                       # Show index health: sources, skill counts, DB path
pg doctor                       # Check database integrity
pg doctor --reset-dead          # Restore bundles hidden after install errors
pg update                       # Update promptgraph-mcp to latest version

# Search & discovery
pg search <query>               # Semantic search across your skills
pg marketplace                  # Browse community skill bundles (TUI)

# Skill graph
pg plan <skill>                 # DAG execution plan: order, parallel levels, cycle detection
pg duplicates                   # Find near-duplicate / overlapping skills

# Install
pg install <id>                 # Install a skill by marketplace ID (pg-xxxxxx)
pg import <github-url>          # Import skills directly from a GitHub repo URL
pg add-dir <path>               # Index skills from a local folder (any platform)

# Bundles
pg bundle install <id>          # Install a bundle by ID
pg bundle update [repo]         # Pull latest from installed GitHub bundles
pg bundle add-repo <owner/repo> # Publish your GitHub repo to the registry (requires gh)

Where your skills can live

PromptGraph scans each registered source folder recursively, so any layout works:

my-skills/
  commit-message.md                  # flat file — name from filename
  refactor/SKILL.md                  # folder skill — name from the folder ("refactor")
  cloud/deploy/SKILL.md              # nested categories — all found
  .github/skills/my-skill/SKILL.md   # GitHub Copilot / agent convention
  .claude/skills/...                 # Claude dot-folder

• Subfolders at any depth are scanned.
• Generic filenames (SKILL.md, index.md, agent.md, …) take their name from the parent folder, so cloud/deploy/SKILL.md and cloud/infra/SKILL.md stay distinct instead of colliding.
• Dot-folders .github/{skills,prompts,agents,commands}, .claude/, .opencode/ are indexed. Other .github paths (workflows, plugins, …) are skipped.
• Doc/meta files (README, CHANGELOG, LICENSE, files in docs/, tests/, assets/, …) are filtered out automatically.

To index a folder that isn't a configured source:

pg add-dir /path/to/skills      # registers it + indexes recursively
pg status                       # confirm it shows up with the right count

Data & config location

PromptGraph stores its config, SQLite DB, and ANN index in:

• ~/.promptgraph/ — fresh installs on any platform
• ~/.claude/.promptgraph/ — kept for existing Claude Code installs (not migrated, so the index isn't orphaned)

Your skill files stay wherever you put them (the platform skills dir or any add-dir folder) — only the derived index lives here.

Skill orchestration — pg → pg-chain

pg setup installs two router skills:

• pg — single lookup: search → read → execute one skill for a task.
• pg-chain — orchestrator: wraps pg in a controlled loop for multi-step tasks. The model runs a skill, reassesses, finds the next skill, runs it, and repeats until the goal is met — following explicit skill chains (pg_callees) and discovering new ones (pg_search) as needs emerge.

pg-chain has hard stop conditions so it can't loop forever: goal met, max 7 skills per chain, a repeat-guard (never re-run the same skill on the same sub-task), and a no-progress guard. It keeps a visible Goal / Done / Now / Left ledger so the chain is auditable.

"Add a feature flag, make sure nothing broke, and write the commit."
  → feature-flag ✓ → safe-verify ✓ → commit-message ✓  (3 skills chained)

Use pg for one-step tasks, pg-chain when a request clearly spans several skills.

OpenCode — /pg slash commands

After pg setup opencode, two slash commands are available inside OpenCode:

• /pg <query> — semantic search; returns the matching skill content
• /pg-list — lists all indexed skills

These are MCP prompts, not tools — they appear in the / command palette.

Marketplace

Browse and install community skill bundles:

pg marketplace              # Interactive TUI browser
pg install pg-xxxxxx        # Install by bundle ID
pg bundle install pg-xxxxxx # Same, explicit subcommand form

Bundles marked with 🔧 include tool scripts (.py, .sh, .js) alongside .md skill files. Scripts are installed to the platform's skills directory and made executable automatically.

Publishing

Publishing to the registry requires the GitHub CLI signed in:

gh auth login               # one-time setup

Publish your own skill: Use the pg_marketplace_publish MCP tool from inside Claude. It creates a Gist and automatically files a registry issue — no browser step, no paste.

Publish a GitHub repo as a bundle:

pg bundle add-repo <owner/repo>       # auto-submits registry issue
pg bundle add-repo <owner/repo> --push # same, with git push to the repo first

The registry bot reads the submitted JSON and publishes within minutes.

Skill bundles with tools

A bundle can ship both skill files (.md) and tool scripts (.py, .sh, .bash, .js, .ts, .rb). When installed:

• All .md files go to the skills directory
• Script files are cloned alongside them (sparse-checkout fetches them with the skills)
• On Linux/macOS scripts are made executable (chmod +x)

For repo bundles (pg bundle add-repo <owner/repo>), scripts are detected automatically — has_tools and the 🔧 badge are set from the real files in the repo, no manifest needed. For skill-list bundles, list scripts explicitly in tool_files.

How it works

1. Your .md skills are embedded with BGE-Small-EN (fastembed, local, no API key)
2. Embeddings are stored in SQLite + HNSW index
3. When Claude calls pg_search("refactor without breaking tests"), only the matching skill is loaded into context
4. Skills are scored — pg_top_rated returns the best-performing ones

Memory usage: The first index uses ~0.85 GB RAM (batch=16 default). Override with PG_EMBED_BATCH if needed. Subsequent reindexes of unchanged content are near-instant thanks to a persistent embed cache.

Troubleshooting

Only some of my skills got indexed: Check pg status for the Found N files count. If it's lower than expected:

• The skills live outside a registered source → pg add-dir <that-folder>.
• Generic SKILL.md files used to collide on name (fixed) — make sure you're on the latest version (pg update).
• Files named like docs (README, 01-intro, …) or under docs//tests/ are filtered by design.

Marketplace shows no bundles:

pg doctor --reset-dead

Reindex stuck / no progress: Progress bar with ETA appears automatically. First run downloads the embedding model (~45 MB).

EBUSY error on pg update: Close any terminals running pg commands, then run pg update again.

OpenCode not seeing MCP: Run pg setup opencode — it writes the correct { "type": "local", "command": ["cmd", "/c", "npx", "promptgraph-mcp"] } entry to ~/.config/opencode/opencode.json.

Publishing fails with "gh auth": Install the GitHub CLI and run gh auth login.

Requirements

• Node.js ≥ 18
• ~45 MB disk for the embedding model (downloaded on first use)
• GitHub CLI — only needed for publishing to the marketplace

License

MIT