Toolkit Ai

████████╗ ██████╗  ██████╗ ██╗     ██╗  ██╗██╗████████╗
╚══██╔══╝██╔═══██╗██╔═══██╗██║     ██║ ██╔╝██║╚══██╔══╝
   ██║   ██║   ██║██║   ██║██║     █████╔╝ ██║   ██║
   ██║   ██║   ██║██║   ██║██║     ██╔═██╗ ██║   ██║
   ██║   ╚██████╔╝╚██████╔╝███████╗██║  ██╗██║   ██║
   ╚═╝    ╚═════╝  ╚═════╝ ╚══════╝╚═╝  ╚═╝╚═╝   ╚═╝

toolkit-ai

A package manager for AI coding assistants — manage skills, agents, and MCP servers across Claude Code, Codex, Amp, GitHub Copilot, and Cursor from any GitHub repo.

[](https://www.npmjs.com/package/toolkit-ai) [](https://www.npmjs.com/package/toolkit-ai) [](https://github.com/barleviatias/toolkit-ai) [](https://github.com/barleviatias/toolkit-ai/actions/workflows/ci.yml) [](https://www.typescriptlang.org/) [](LICENSE)

[Install](#install) · [Quick Start](#quick-start) · [Resource Types](#resource-types) · [TUI](#interactive-tui) · [CLI](#cli-commands) · [Security](#security)

---

Why toolkit-ai

If your team works across more than one AI coding assistant, you've hit this wall:

• Every tool keeps its own config (~/.claude/, ~/.cursor/, ~/.codex/, ~/.copilot/, ~/.config/amp/)
• Skills, subagents, and MCP server configs live in different formats
• There's no shared catalog, no versioning, no security review step
• Shipping a skill to your team means a wiki page and a prayer

toolkit-ai treats your AI tooling like dependencies. Point it at GitHub repos, browse everything in one TUI, install across all five tools at once, and keep a lockfile with content hashes so you know when something changed.

npx toolkit-ai

Features

• One catalog, five tools — skills, agents, and MCP servers installed into Claude Code, Codex, Amp, GitHub Copilot, and Cursor from a single command
• Source-driven — every resource comes from a GitHub or Bitbucket repo you control; no bundled content
• Security scanner — blocks curl-to-shell, reverse shells, invisible Unicode injection, SSRF, path traversal, and more before install
• Interactive TUI — React Ink browser, installer, and updater with search, filters, and multi-select
• Content-hashed lockfile — toolkit check shows exactly what's outdated; toolkit update applies changes
• Zero runtime dependencies — single bundled executable, runs on npx without a clone
• TypeScript strict mode — 31 unit + integration tests, typechecked on Node 20 + 22

---

Table of Contents

• [Install](#install)
• [Quick Start](#quick-start)
• [Resource Types](#resource-types)
• [Skills](#skills) · [Agents](#agents) · [MCPs](#mcps) · [Bundles](#bundles)
• [Interactive TUI](#interactive-tui)
• [CLI Commands](#cli-commands)
• [External Sources](#external-sources)
• [Security](#security)
• [What We Scan](#what-we-scan) · [Trust Model](#trust-model) · [Security Disclosure](#security-disclosure)
• [Create Your Own Resources](#create-your-own-resources)
• [How Storage Works](#how-storage-works)
• [Related Projects](#related-projects)
• [Development](#development)

---

Quick Start

# 1. Launch the interactive browser
npx toolkit-ai

# 2. Or install something in one command
npx toolkit-ai source add vercel-labs/agent-skills
npx toolkit-ai skill brainstorming

# 3. Check what's installed and what needs updating
npx toolkit-ai list
npx toolkit-ai check

---

Install

# Recommended — install once, get the short `toolkit` command,
# and get a clear update notice when a newer version is available.
npm install -g toolkit-ai
toolkit                    # launch the TUI
toolkit --help             # CLI reference

# One-off use (never installs anything globally)
npx toolkit-ai

Without npm

Don't have npm (or just don't want to use it)? Pipe the installer instead. It downloads the bundled .mjs from GitHub Releases and drops it in ~/.local/bin (or /usr/local/bin). Node 20+ on PATH is the only requirement.

curl -fsSL https://raw.githubusercontent.com/barleviatias/toolkit-ai/main/install.sh | bash

Pin a specific version or override the install dir:

AI_TOOLKIT_VERSION=v2.1.6 curl -fsSL .../install.sh | bash
AI_TOOLKIT_BIN_DIR=~/bin   curl -fsSL .../install.sh | bash

Update notices: toolkit-ai checks the npm registry once per 24h and, if a newer version exists, prints the exact command to run: npm install -g toolkit-ai@latest. It does not auto-update. Checks are skipped on CI (CI=true, GITHUB_ACTIONS, CODESPACES, etc.) and when stderr isn't a TTY. Opt out with TOOLKIT_NO_UPDATE_CHECK=1.

---

Resource Types

The toolkit manages four types of resources that extend AI coding assistants.

Skills

Markdown files that teach AI agents new capabilities, domain knowledge, or workflows. Each skill is a directory containing a SKILL.md with YAML frontmatter.

skills/
  api-design/
    SKILL.md          # Instructions for the AI agent
    references/       # Optional supplementary docs

Example SKILL.md:

---
name: api-design
description: >
  REST API design conventions and best practices.
  Use when creating or reviewing API endpoints.
---

# API Design

## When to use

Apply these conventions when designing new endpoints or reviewing API PRs.

## Guidelines

- Use plural nouns for resource names (`/users`, not `/user`)
- Return 201 for successful creation, 204 for deletion
- Include pagination for list endpoints

Installs to detected targets: ~/.claude/skills/, ~/.copilot/skills/, ~/.agents/skills/ (Codex), ~/.config/amp/skills/

Agents

Specialized AI worker definitions with their own tool access, model preferences, and behavior. Agents run in isolated context and return a summary to the main conversation.

Example code-reviewer.agent.md:

---
name: code-reviewer
description: >
  Reviews code changes for bugs, security issues, and style violations.
tools:
  - read
  - grep
  - glob
---

# Code Reviewer

You are a code review agent. Given a set of file changes, you:

1. Check for common bugs and edge cases
2. Flag security concerns (SQL injection, XSS, etc.)
3. Verify style consistency with the codebase
4. Suggest concrete improvements with code examples

Installs to detected targets: ~/.claude/agents/, ~/.copilot/agents/, plus generated Codex custom agents in ~/.codex/agents/*.toml

MCPs

Model Context Protocol server configurations. The toolkit reads these JSON files and registers the MCP server into each AI tool's config file. For Codex, it writes TOML under ~/.codex/config.toml; for the other tools, it writes JSON config entries. The toolkit does not run the server itself.

Example supabase-mcp.json:

{
  "name": "supabase-mcp",
  "description": "Connect to Supabase for database queries and auth",
  "type": "sse",
  "url": "https://mcp.supabase.com/v1/sse",
  "setupNote": "After install, restart your agent to authorize."
}

| Field | Required | Description | |-------|----------|-------------| | name | Yes | Identifier — used as the key in target config files | | description | Yes | Shown in the TUI catalog | | type | No | Transport hint for tools that expect it | | url | No | Streamable HTTP server URL | | command | No | STDIO server command | | args | No | Command arguments for STDIO servers | | env | No | Environment variables for STDIO servers | | setupNote | No | Shown to the user after install (e.g. "restart your agent") |

What happens on install: The toolkit writes MCP settings into each tool's native config format:

~/.claude/settings.json    → mcpServers.
~/.cursor/mcp.json         → mcpServers.
~/.vscode/mcp.json         → servers.
~/.copilot/mcp-config.json → mcpServers.
~/.claude.json             → mcpServers.
~/.codex/config.toml       → [mcp_servers.]

Only config files that already exist locally are updated for editor-specific integrations. Global configs such as ~/.claude.json and ~/.codex/config.toml are created only when that target app is detected. Run toolkit targets to see what the toolkit will write to.

Bundles

Curated collections that reference skills, agents, and MCPs by name. Installing a bundle installs all referenced items together — think of it as a preset or starter pack.

Example fullstack-starter.bundle.json:

{
  "name": "fullstack-starter",
  "description": "Essential skills and MCPs for full-stack development",
  "skills": ["api-design", "test-driven-development", "code-review"],
  "agents": ["code-reviewer"],
  "mcps": ["supabase-mcp", "playwright-mcp"]
}

Behavior:

• toolkit bundle fullstack-starter installs all 5 items
• toolkit remove bundle fullstack-starter removes all items from the bundle
• Items can still be installed/removed individually

Plugins

Plugins are bundled packages of skills, agents, commands, and MCP servers, discovered as a first-class resource type and installed across every detected provider — Claude Code, Codex, GitHub Copilot, Cursor, VS Code, and Amp.

Discovery — manifest formats accepted:

• .claude-plugin/plugin.json — Claude Code's official plugin layout
• .codex-plugin/plugin.json — Codex's native plugin layout
• plugin.json at the plugin root — generic / cross-tool plugin packages
• Plugins already installed by Claude Code's /plugin install — read from

~/.claude/plugins/installed_plugins.json and surfaced under the synthetic claude source. No source configuration needed; they appear automatically in toolkit list and the TUI catalog. Run toolkit plugin on one to mirror it across every other detected provider, using native plugin installs where available and decomposed copies only for fallback providers. Toolkit never writes to Claude's plugin state — remove plugin only removes the toolkit-managed copies.

• Plugins already installed by Codex — read from ~/.codex/config.toml

[plugins."@"] entries plus ~/.codex/plugins/cache////, then surfaced under the synthetic codex source. Run toolkit plugin to mirror it across the other detected providers.

• Plugins already installed by GitHub Copilot CLI's copilot plugin install —

discovered by walking ~/.copilot/installed-plugins/_direct/ (the per-plugin install root the Copilot CLI populates) and surfaced under the synthetic copilot source. Same flow as the Claude case: appear automatically in toolkit list, run toolkit plugin to mirror it across every other detected provider. Toolkit never writes back to Copilot's installed- plugins tree — remove plugin only removes the toolkit-managed copies.

Manifest path overrides — for plugins that don't fit Claude's layout:

Most Claude plugins put skills directly under skills//SKILL.md and agents directly under agents/.md. Cross-tool plugin packages (AMS, Radware bundles, anything with per-tool adapters) often nest these — e.g. skills/universal/foo/SKILL.md, skills/stack-specific/backend-java/foo/SKILL.md, agents/adapters/copilot/reviewer.agent.md.

The plugin.json manifest may declare explicit content roots so the toolkit walks the right places:

{
  "name": "radware-ams",
  "skills": [
    "skills/universal/",
    "skills/stack-specific/backend-java/",
    "skills/stack-specific/frontend-react/"
  ],
  "agents": "agents/adapters/copilot/",
  "commands": "commands/",
  "mcps": "mcps/"
}

Each field accepts a string or an array of strings, all relative to the plugin root. The toolkit walks each declared root recursively for SKILL.md / *.agent.md / *.md / *.prompt.md / *.mcp.json, then installs or mirrors across every detected provider exactly as it does for Claude-shaped plugins. When fields are absent, the conventional dirs (skills/, agents/, commands/, root .mcp.json) are scanned instead.

Install — what happens to each component:

Installing a plugin uses each provider's native plugin system when one is available, and decomposes only for providers that do not have a plugin registry:

• Claude Code → ~/.claude/plugins/cache/toolkit-ai///
• Codex → ~/.codex/plugins/cache/toolkit-ai///
• GitHub Copilot CLI → ~/.copilot/installed-plugins/toolkit-ai//
• Cursor / VS Code / Amp → decomposed skills, agents, commands, and MCP config in the native per-user locations those tools already read
• commands/.md → transformed *.prompt.md for VS Code / Insiders
• .mcp.json → embedded in native plugin manifests for Claude Code, Codex, and GitHub Copilot so MCPs appear under the plugin; decomposed into user MCP configs only for tools without a native plugin registry (.cursor/mcp.json, .vscode/mcp.json, .config/amp/settings.json, etc.)

The result is that the same plugin works in every assistant the user has installed, in each one's own native shape — no provider-specific plugin machinery required on the consumer side. Native plugin installs deliberately do not also copy the same skills/agents/MCPs into Claude/Copilot/Codex user dirs, because that duplicates entries in provider UIs.

For Codex native plugin installs, command files are copied into the plugin's commands/ directory with only Codex-safe frontmatter (description and argument-hint). Claude-only metadata such as name, phase, persona, or model is stripped from the Codex copy so slash commands can be discovered.

Native Copilot plugin registration: when GitHub Copilot CLI is detected, plugin install also writes a real entry to Copilot's plugin manager — copies the plugin tree to ~/.copilot/installed-plugins/toolkit-ai//, adds to ~/.copilot/config.json installedPlugins[], enables it in ~/.copilot/settings.json. This makes the plugin show up in Copilot's "Plugins" UI panel, not just as decomposed skills/agents on disk. toolkit remove plugin mirrors this — drops the registry entry, disables in settings, removes the cache dir.

Native Codex plugin registration: when Codex is detected, plugin install also writes a real Codex plugin install — copies the scoped plugin tree to ~/.codex/plugins/cache/toolkit-ai///, registers a local toolkit-ai marketplace in ~/.codex/config.toml, and enables [plugins."@toolkit-ai"]. Codex then loads the plugin from its own plugin system instead of only seeing decomposed standalone skills/agents. toolkit remove plugin removes the config entry and cache tree.

Hooks (hooks/hooks.json). Toolkit refuses to merge a plugin's hooks into the user's ~/.claude/settings.json (those commands run on every tool call across every repo and the security scanner doesn't cover them yet), but a plugin-tree hooks file is a different story: each tool's plugin manager loads hooks/hooks.json from inside the plugin's own install dir and scopes the hooks to that plugin's lifecycle. The toolkit copies the hooks/ directory verbatim along with the rest of the plugin tree, so any hooks/hooks.json the plugin ships rides along to Claude / Copilot / Codex plugin installs.

Per-tool hooks.json swap. Claude, Copilot, and Codex disagree on hook schema — Claude uses PascalCase events and ${CLAUDE_PLUGIN_ROOT}, Copilot uses camelCase events with no documented plugin-root env var, Codex's hook spec is not public. A plugin can ship multiple hook configs and let the installer pick the right one per tool. The canonical hooks/hooks.json is treated as the Claude flavor; if the plugin also ships hooks/configs/copilot.hooks.json or hooks/configs/codex.hooks.json, the installer for that tool reads the matching template, substitutes the literal string __AMS_PLUGIN_ROOT__ with the install destination directory, and writes the result over hooks/hooks.json inside that tool's install. Claude's install is never swapped — it keeps the canonical file. During the substitution, toolkit normalizes backslashes to forward slashes so Git Bash on Windows receives paths it can execute safely.

plugin/
├─ hooks/
│  ├─ hooks.json                    ← canonical

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [barleviatias](https://github.com/barleviatias)
- **Source:** [barleviatias/toolkit-ai](https://github.com/barleviatias/toolkit-ai)
- **License:** MIT
- **Homepage:** https://www.npmjs.com/package/toolkit-ai

Install and usage instructions live in the source repository linked above.