✨ What is agent-toolkit?

agent-toolkit is a modular collection of skills, agent personas, MCP configuration templates, and loop engineering patterns that work across all major AI coding assistants. Instead of maintaining separate prompt libraries for each tool, you keep one source of truth and deploy exactly what each tool needs.

One toolkit. Any coding assistant. Zero duplication.

# Native V CLI (any channel below), then:
agent-toolkit install
agent-toolkit doctor

Key Concepts

🚀 Quick Install

Recommended: the product CLI is the native V binary. PyPI/uv is a thin launcher over that binary (ADR-021).

# GitHub Release — native V binary + SHA256SUMS (v1.11.0+)
# https://github.com/ulises-jeremias/agent-toolkit/releases/latest

# Homebrew
brew tap ulises-jeremias/homebrew-tap && brew install agent-toolkit

# AUR (Arch) — native V binary; not the Python AUR package
yay -S agent-toolkit-bin

# PyPI launcher (execs bundled V; ADR-021)
uv tool install 'agent-toolkit-cli>=1.11.0'
uvx --from 'agent-toolkit-cli>=1.11.0' agent-toolkit install

# npm
npm i -g agent-toolkit-cli

agent-toolkit install    # auto-detects Claude, Cursor, OpenCode, Windsurf, Pi, Copilot
agent-toolkit doctor     # verify everything is set up

→ Full walkthrough: docs/INSTALLATION.md

Advanced install methods

Use these only when the primary CLI flow above does not fit your setup.

/plugin marketplace add ulises-jeremias/agent-toolkit
/plugin install agent-toolkit-core@agent-toolkit
/plugin install agent-toolkit-agents@agent-toolkit
/plugin install agent-toolkit-forge@agent-toolkit

# Interactive — browse / install from the Marketplace tab
cursor-agent
# then type: /plugin

cursor-agent --plugin-dir ./plugins/agent-toolkit-core
cursor-agent --plugin-dir ./plugins/agent-toolkit-agents
cursor-agent --plugin-dir ./plugins/agent-toolkit-forge

# Symlink into Cursor's local plugin dir, then reload the window
mkdir -p ~/.cursor/plugins/local
ln -s "$(pwd)/plugins/agent-toolkit-core" ~/.cursor/plugins/local/agent-toolkit-core
ln -s "$(pwd)/plugins/agent-toolkit-agents" ~/.cursor/plugins/local/agent-toolkit-agents
ln -s "$(pwd)/plugins/agent-toolkit-forge" ~/.cursor/plugins/local/agent-toolkit-forge

npx skills add ulises-jeremias/agent-toolkit -g

brew tap ulises-jeremias/homebrew-tap && brew install agent-toolkit
yay -S agent-toolkit-bin   # Arch Linux (AUR) — GitHub Release V binary; not the Python AUR package
npm i -g agent-toolkit-cli # optionalDependencies platform packages
docker pull ghcr.io/ulises-jeremias/agent-toolkit

git clone https://github.com/ulises-jeremias/agent-toolkit ~/.agent-toolkit
./make.vsh install-cli    # canonical V binary → ~/.local/bin (or --prefix=…)
agent-toolkit install

git clone https://github.com/ulises-jeremias/agent-toolkit ~/.agent-toolkit

# Claude Code — reference in .claude/settings.json
# Cursor — copy profiles/cursor/rules/*.mdc → .cursor/rules/
# OpenCode — copy profiles/opencode/ → ~/.config/opencode/
# Copilot — copy profiles/copilot/copilot-instructions.md → .github/
# Windsurf — copy profiles/windsurf/ → ~/.codeium/windsurf/
# Pi Agent — copy profiles/pi/skills/ → ~/.pi/agent/skills/

🖥️ Supported Tools

🛠️ Skills — catalog via agent-toolkit inventory

All skills use SKILL.md frontmatter only — no skill.json required. Fully compliant with the Agent Skills spec. Live counts: agent-toolkit inventory / catalogs/skill-catalog.yaml (source of truth, not README badges). Marketplace plugins ship a subset (core + forge); agent-toolkit-complete is the full catalog.

Browse the full catalog: catalogs/skill-catalog.yaml · membership matrix docs/SKILL_PRODUCT_MATRIX.md (scripts/generate-skill-matrix.vsh --check in CI) · regenerate with ./scripts/validate-skills.vsh (CI) and inspect live inventory via agent-toolkit inventory (counts shown in badges above are generic — use inventory for accurate numbers)

Loading skills in Claude Code

// .claude/settings.json
{
  "skills": [
    "ulises-jeremias/agent-toolkit/skills/core/assistant",
    "ulises-jeremias/agent-toolkit/skills/delivery/workflow-generic-project",
    "ulises-jeremias/agent-toolkit/skills/delivery/bug"
  ]
}

🤖 Agent Personas

Tool-agnostic agent persona definitions in agents/ (live count: agent-toolkit inventory / catalogs/agent-catalog.yaml). Any supported AI coding assistant can import these via its profile config.

Full catalog: catalogs/agent-catalog.yaml · personas on disk under agents/ (see inventory)

🔄 Loop Engineering

Loops are recurring agentic workflows that run on a schedule or cadence. They follow a three-tier mutation-safety model enforced by loop-gh-gate (cadence is independent of tier):

Loop Templates

Stage vs Layer: Loop tiers L1/L2/L3 are mutation-safety Stages (Loop Engineering discipline), not ownership Layers. See docs/ARCHITECTURE.md for the L1 Machine / L1.5 Toolkit / L3 Workspace layer model.

Each loop template lives in loops/<name>/ (see agent-toolkit inventory for live count) with a loop.yaml definition (prompt in request:). At runtime the runner writes STATE.md and report.md under that directory.

🔗 MCP Templates

Ready-to-use Model Context Protocol configuration templates. Drop into your MCP config directory and substitute your credentials.

Templates live in mcp/templates/ (7 providers). Each file is a .json with clearly marked placeholder values.

📦 Plugins — Agent Plugins 1.0 Portable

New: Every plugin in plugins/ now ships as an Agent Plugins 1.0 portable bundle (plugin.json + skills/ + mcp.json) for Cursor, VS Code, GitHub Copilot, ChatGPT/Codex, Kiro — plus legacy .claude-plugin/ for Claude Code (dual emit until Claude supports the spec). See docs/AGENT_PLUGINS.md.

Product bundles are declared in distributions/products.yaml. Four products are built for every compatible client; three ship in the Claude Code and Cursor marketplaces:

Plugin manifests: .claude-plugin/marketplace.json · .cursor-plugin/marketplace.json · plugins/<id>/plugin.json (Agent Plugins $schema: https://agent-plugins.org/schemas/1.0.0/plugin.schema.json) · plugins/<id>/mcp.json (where applicable)

🎯 Solution Packs

Packs bundle skills, agents, and loops for a specific team context. Load a pack to bring in everything a setup needs in one step.

Browse packs: packs/

📚 Documentation

🌐 Ecosystem

agent-toolkit is the Capability + Runtime layer (L1.5) in a four-layer ownership stack. It exposes two internal planes (Capability and Runtime) that share one binary and one release — see docs/ARCHITECTURE.md. Companion repos:

Stages vs Layers: L0–L3 in Context/Harness/Loop Engineering is discipline Stages (mutation-safety / capability maturity), not ownership Layers L1/L1.5/L3. See docs/ARCHITECTURE.md terminology note and docs/LOOPS.md tier Stages. Loop tier L1/L2/L3 below is Stages, not Layers.

agentic-workstation installs the V CLI during chezmoi apply (Homebrew, AUR agent-toolkit-bin, GitHub Release, or the PyPI launcher). Running agent-toolkit install deploys skills and profiles to all detected AI tools.

agentic-harness is an opinionated workspace scaffold that uses agent-toolkit loop, agent-toolkit memory, agent-toolkit devcompanion, agent-toolkit project, and agent-toolkit swarm as its primary CLI interface.

🏗️ Architecture

One source of truth, deployed per-tool. See docs/ARCHITECTURE.md for ownership Layers L1/L1.5/L3 + Project Overlay and the two internal planes (Capability vs Runtime, ADR-015 / ADR-026). plugins/ is canonical compiler output; profiles/ is a deprecated install overlay (ADR-004).

agent-toolkit/                 # L1.5 Toolkit — two planes, one binary
├── skills/                    # Capability: SKILL.md by domain (inventory is SoT)
├── agents/                    # Capability: tool-agnostic persona definitions
├── plugins/                   # Capability: compiler output — canonical (build --check)
├── profiles/                  # Capability: deprecated overlay — fallback only (ADR-004)
├── distributions/             # Capability: products.yaml composition SoT
├── mcp/templates/             # Capability: provider templates + registry
├── packs/                     # Capability: docs-only packs (ADR-006)
├── loops/                     # Runtime: loop templates (inventory is SoT)
├── catalogs/                  # generated — skill/agent/loop catalogs
├── schemas/                   # JSON schemas for validation
├── modules/                   # V CLI — Capability + Runtime planes
├── docs/                      # How-to guides and reference docs
├── examples/                  # Worked examples
└── scripts/                   # Install and validation scripts

Live counts: agent-toolkit inventory (not hardcoded).

Automation Stages (Loop Engineering)

Stage vs Layer: L1/L2/L3 below are Stages (Loop Engineering mutation-safety), not ownership Layers.

✅ Validation

agent-toolkit doctor          # consumer health check
./scripts/validate-skills.vsh
./scripts/validate-loops.vsh

The .vsh validators exit non-zero on failure with human-readable error messages. They run automatically in CI via the Validate workflow. Contributors: CONTRIBUTING.md (./make.vsh test, ./make.vsh build-cli).

🤝 Contributing

Contributions welcome. Please read CONTRIBUTING.md before opening a PR.

1. Fork the repo and create a branch: feat/my-skill
2. Add your skill under the appropriate domain in skills/ — use SKILL.md frontmatter only
3. Run ./scripts/validate-skills.vsh — all checks must pass
4. Open a PR with a clear description of what the skill does and which tools it supports

See How to add a skill for the full authoring guide.

Showcase

See SHOWCASE.md for community usage examples and pack walkthroughs.

👥 Contributors

Made with contributors-img.