toolkit-ai

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

Table of Contents

• Install
• 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
• Development

Install

npx toolkit-ai            # run directly, no install
npm install -g toolkit-ai  # or install globally
toolkit                   # launch after global install

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: ~/.claude/skills/, ~/.copilot/skills/, ~/.agents/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: ~/.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 if missing.

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 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 remove <name>       # Remove a source
toolkit refresh                    # Re-fetch all external sources

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

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 [email protected]:owner/repo.git

Discovery conventions

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

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

Every item from external sources is automatically scanned before installation. Items that fail the scan are blocked and cannot be installed without --force.

What we scan

Skills & Agents (text content analysis):

MCPs (URL and config analysis):

Trust model

• Internal resources (bundled with the toolkit): Scanned but findings are downgraded from block to warn. These are considered trusted.
• External resources (from configured sources): Fully scanned. Blocked items cannot be installed unless you pass --force.
• The scanner runs automatically on every install. You can also run it manually:

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

TUI indicators

• Items with blocking findings show a red ✕ blocked badge
• Items with warnings show a yellow ⚠ badge
• 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

~/.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 dev      # Build with watch
npm test         # Lint + validate catalog
npm link         # Link globally for testing

Tech stack

• React Ink — terminal UI framework
• tsup — bundles into a single zero-dependency executable
• TypeScript — full type safety

License

MIT