# Toolkit Ai

> Package manager for AI coding assistants — manage skills, agents & MCPs across Claude Code, Codex, Copilot, and Cursor

- **Type:** MCP server
- **Install:** `agentstack add mcp-barleviatias-toolkit-ai`
- **Verified:** Pending review
- **Seller:** [barleviatias](https://agentstack.voostack.com/s/barleviatias)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [barleviatias](https://github.com/barleviatias)
- **Source:** https://github.com/barleviatias/toolkit-ai
- **Website:** https://www.npmjs.com/package/toolkit-ai

## Install

```sh
agentstack add mcp-barleviatias-toolkit-ai
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

# 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.

```bash
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

```bash
# 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

```bash
# 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.

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

Pin a specific version or override the install dir:

```bash
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`:**

```markdown
---
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`:**

```markdown
---
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`:**

```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`:**

```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:

```json
{
  "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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-barleviatias-toolkit-ai
- Seller: https://agentstack.voostack.com/s/barleviatias
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.