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

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
• Quick Start
• Resource Types
  • Skills · Agents · MCPs · Bundles
• Interactive TUI
• CLI Commands
• External Sources
• Security
  • What We Scan · Trust Model · Security Disclosure
• Create Your Own Resources
• How Storage Works
• Related Projects
• 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 self-updates in the background on every launch.
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

Auto-updates: when launched from a global npm install, toolkit-ai checks the npm registry once per 24h and, if a newer version exists, silently runs npm install -g toolkit-ai@latest in the background. The upgrade takes effect on the next launch. Never runs when installed via npx, npm link, or a local clone. Auto-skipped on CI (CI=true, GITHUB_ACTIONS, CODESPACES, etc.) and when stderr isn't a TTY. Opt out with TOOLKIT_AUTO_UPDATE=off (or TOOLKIT_NO_UPDATE_CHECK=1 to disable the check entirely).

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."
}

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

~/.claude/settings.json    → mcpServers.<name>
~/.cursor/mcp.json         → mcpServers.<name>
~/.vscode/mcp.json         → servers.<name>
~/.claude.json             → mcpServers.<name>
~/.codex/config.toml       → [mcp_servers.<name>]

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

Interactive TUI

Run toolkit with no arguments to launch the interactive interface:

toolkit

Keyboard shortcuts

Global: Tab switch tabs · q quit

Catalog & Installed:

Sources:

CLI Commands

# Install
toolkit skill <name>               # Install a skill
toolkit agent <name>               # Install an agent
toolkit mcp <name>                 # Register an MCP server
toolkit bundle <name>              # Install a bundle (all items at once)

# Remove
toolkit remove skill <name>        # Remove a skill
toolkit remove agent <name>        # Remove an agent
toolkit remove mcp <name>          # Deregister an MCP server
toolkit remove bundle <name>       # Remove a bundle

# Browse & update
toolkit list                       # List all available items
toolkit targets                    # Show detected install targets
toolkit settings                   # Show install/cache settings
toolkit check                      # Check for available updates
toolkit update                     # Update all installed items

# Sources
toolkit source add <repo>          # Add an external source
toolkit source list                # List configured sources
toolkit source disable <name>      # Temporarily skip a source (stays in config)
toolkit source enable <name>       # Re-enable a disabled source
toolkit source remove <name>       # Remove a source entirely
toolkit refresh                    # Re-fetch all external sources

# Settings
toolkit settings install-mode copy # Install skills/agents as file copies
toolkit settings install-mode link # Install skills/agents as symlinks
toolkit settings cache 24h         # Refresh stale source cache after 24h
toolkit settings cache 0           # Always check sources on launch/refresh
toolkit settings concurrency 4     # Fetch up to 4 sources in parallel

# Security
toolkit scan                       # Scan all available items
toolkit scan skill <name>          # Scan a specific skill

# Scaffold
toolkit init [dir]                 # Create a boilerplate skill repo

# Meta
toolkit --version                  # Show version
toolkit --help                     # Full usage info

Examples:

# Add a source and install a skill from it
toolkit source add vercel-labs/agent-skills
toolkit skill brainstorming

# Install an entire bundle
toolkit bundle fullstack-starter

# Check what's outdated and update everything
toolkit check
toolkit update

# Scan before installing something you don't trust
toolkit scan skill suspicious-skill

# Install in CI — fail the pipeline if the scanner finds anything risky
toolkit skill suspicious-skill --strict

# Symlink a skill/agent to the source cache instead of copying it
toolkit skill brainstorming --link

# Make symlink installs the default for future TUI and CLI installs
toolkit settings install-mode link

External Sources

All content comes from external repos. The toolkit ships with no bundled resources — you add GitHub or Bitbucket repos as sources, and the toolkit discovers resources inside them.

# Add sources
toolkit source add owner/repo
toolkit source add https://github.com/owner/repo
toolkit source add https://bitbucket.org/owner/repo
toolkit source add git@github.com:owner/repo.git

Discovery conventions

The toolkit scans source repos recursively and discovers resources by file naming conventions:

Settings

The TUI includes a Settings tab for install mode, source cache duration, parallel source refreshes, detected providers, and the config/cache paths. The same values are stored in ~/.toolkit/config.json and used by headless CLI commands.

• installMode: "copy" installs stable snapshots of skills/agents.
• installMode: "link" symlinks skills/agents to the source cache, useful when you want refreshes and local source edits to be reflected without reinstalling.
• cacheTTL controls how long source clones are considered fresh before the next launch or refresh fetches updates.
• cacheTTL: 0 always checks remote sources.
• sourceConcurrency controls how many source repos fetch in parallel.

Directories named node_modules, .git, dist, build, .next, and coverage are automatically skipped.

Caching

Sources are shallow-cloned (--depth 1) and cached at ~/.toolkit/cache/. The cache refreshes automatically every 24 hours. Force a refresh with:

toolkit refresh                    # re-fetch all sources
toolkit source refresh my-source   # re-fetch a specific source

Default sources

The toolkit ships with two default sources:

{
  "sources": [
    { "name": "vercel-labs", "type": "github", "repo": "vercel-labs/agent-skills" },
    { "name": "anthropics", "type": "github", "repo": "anthropics/skills" }
  ]
}

Override defaults by creating ~/.toolkit/sources.json.

Security

This tool is built for dev teams — the goal is informed consent, not enforcement. The scanner surfaces risky patterns so you can decide; it does not refuse to install on your behalf.

The model: alert, never block

Running toolkit mcp foo in a terminal means you typed the name and pressed Enter. We don't second-guess that. The TUI is where consent prompts live because the user is browsing and may not know what they clicked on.

What we scan

Skills & Agents (text content analysis across .md/.txt/.json/.yaml/.js/.ts/.html plus executable scripts .sh/.bash/.zsh/.fish/.py/.rb/.pl/.php/.ps1/.bat/.cmd):

MCPs (URL and config analysis):

The MCP scanner also runs every header value, env value, and arg through the same text-pattern rules — an Authorization header that smuggles a curl \| bash payload will surface.

Running the scanner directly

toolkit scan                    # scan everything
toolkit scan skill <name>       # scan a specific skill

Strict mode (CI)

toolkit skill <name> --strict   # exits non-zero if the scan finds a block-severity issue
toolkit update --strict         # same, for bulk updates

Use --strict in pipelines where you'd rather fail a build than install something flagged. Leave it off in day-to-day dev work.

Trust model

• Internal resources (bundled with the toolkit): Scanned, but findings are downgraded from block to warn.
• External resources (from configured sources): Fully scanned. Warnings surface in both the TUI badge and the install log, but the install proceeds unless you pass --strict.
• The scanner runs automatically on every install and on every catalog render — results are cached by content hash so repeats are free.

TUI indicators

• Items with blocking findings show a red ✕ blocked badge (install will trigger a confirmation dialog, not a refusal)
• Items with warnings show a yellow ⚠ badge
• Stdio MCPs always show their command preview in the detail view before install
• Clean items show no badge

Limitations

The scanner is a static analysis tool. It catches common attack patterns but is not a substitute for reviewing code from untrusted sources. It does not:

• Execute code in a sandbox
• Verify cryptographic signatures
• Check for supply chain attacks in dependencies
• Detect obfuscated or novel attack patterns

Always review resources from unknown sources before installing.

Security Disclosure

If you discover a vulnerability in the toolkit or its scanner, please report it responsibly:

1. Do not open a public GitHub issue for security vulnerabilities
2. Email the maintainer or open a private security advisory at github.com/barleviatias/toolkit-ai/security
3. Include steps to reproduce and any relevant details
4. We aim to acknowledge reports within 48 hours

Create Your Own Resources

Scaffold a boilerplate repo to publish your own skills, agents, MCPs, and bundles:

toolkit init my-skills

This creates:

my-skills/
  resources/
    skills/
      example-skill/SKILL.md
    agents/
      example-agent.agent.md
    mcps/
      example-mcp.json
    bundles/
      fullstack-starter.bundle.json
  README.md
  .gitignore

Push to GitHub, then anyone can add it as a source:

toolkit source add your-org/my-skills

How Storage Works

~/.toolkit/
  lock.json              # Tracks installed items, content hashes, timestamps
  sources.json           # Your configured external sources
  cache/                 # Shallow-cloned repos from external sources
    vercel-labs/         #   cached clone of vercel-labs/agent-skills
    anthropics/          #   cached clone of anthropics/skills

Installed items are copied or generated into each tool's config directory:

~/.claude/
  skills/api-design/SKILL.md          # Installed skill
  agents/code-reviewer.agent.md       # Installed agent
  settings.json                       # MCP servers registered here

~/.copilot/
  skills/api-design/SKILL.md          # Same skill, mirrored
  agents/code-reviewer.agent.md

~/.agents/
  skills/api-design/SKILL.md          # Codex-discoverable shared skill

~/.config/amp/
  skills/api-design/SKILL.md          # Amp-discoverable skill
  settings.json                       # MCP servers registered here (amp.mcpServers)

~/.codex/
  agents/code-reviewer.toml           # Generated Codex custom agent
  config.toml                         # MCP servers registered here

~/.cursor/mcp.json                    # MCP servers registered here
~/.vscode/mcp.json                    # MCP servers registered here

The lock file tracks every installed item with a content hash. When a resource changes upstream, toolkit check flags it as outdated and toolkit update applies the new version.

Development

git clone https://github.com/barleviatias/toolkit-ai.git
cd toolkit-ai
npm install
npm run build    # Build → bin/ai-toolkit.mjs
npm run build:dev # Local build with a visible "dev build" tag
npm run dev      # Build with watch
npm test         # Typecheck + 31 unit/integration tests
npm link         # Link globally for testing

Tech stack

• React Ink — terminal UI framework
• tsup — bundles into a single zero-dependency executable
• TypeScript strict mode — full type safety
• node:test — built-in test runner, no framework dependency

See CLAUDE.md for architecture notes and AGENTS.md for contributor guidelines.

Keywords

ai · ai-toolkit · ai-agents · skills · agents · mcp · mcp-server · model-context-protocol · claude · claude-code · codex · copilot · cursor · cursor-ai · cli · tui · ink · developer-tools · plugin-manager · agent-framework · prompt-engineering · skill-management · typescript · package-manager · dotfiles

Roadmap

Post-launch plans live in ROADMAP.md — UX polish (cold-start spinner, ? help overlay), perf work (parallel git clones, atomic fetch), and test-coverage gaps.

License

MIT © Bar Levi Atias