ai-toolkit

Professional-grade AI coding toolkit with multi-platform support. Machine-enforced safety, 107 skills, 44 agents, expanded lifecycle hooks, persona presets, experimental opt-in plugin packs, and benchmark tooling — works with Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, Augment, Google Antigravity, Codex CLI, and opencode, ready in 60 seconds.

What's New in v4.3.0

Minor release. Closes the asymmetry between inject-rule / inject-hook and MCP servers -- external tools (rag-mcp, jira-mcp, custom integrations) can now register MCP templates the same way they register rules and hooks.

• ai-toolkit inject-mcp <file|url>: register an external MCP template into ~/.mcp.json + every editor with a global_path (Claude, Cursor, Codex, Gemini, Windsurf, Cline, Augment, Copilot) in one command.
• ai-toolkit remove-mcp <name>: strip injected servers from ~/.mcp.json and every editor config in one command.
• URL templates + auto-refresh: HTTPS-sourced templates are cached and re-fetched on every ai-toolkit update, just like URL rules and hooks.
• --name and --force flags: explicit source naming for both files and URLs, plus collision-safe overwrites that still protect ai-toolkit built-in entries.

See CHANGELOG.md for full history.

Table of Contents

• Install
• Platform Support
• What You Get
• Architecture
• Key Features
• Key Slash Commands
• Getting Started
• Documentation
• Contributing
• Security
• License
• Changelog

Install

# Option A: install globally (once per machine)
npm install -g @softspark/ai-toolkit
ai-toolkit install

# Option B: try without installing (npx)
npx @softspark/ai-toolkit install

That's it. Claude Code picks up 107 skills, 44 agents, quality hooks, and the safety constitution automatically.

Windows: WSL is the recommended runtime. Native Windows works when Git Bash is available for hook scripts; dependency hints cover winget, Chocolatey, and Scoop. See Windows Support.

Update

npm install -g @softspark/ai-toolkit@latest && ai-toolkit update

Per-Project Setup

cd your-project/
ai-toolkit install --local                        # Claude Code only
ai-toolkit install --local --editors all          # + all editors
ai-toolkit install --local --editors cursor,aider # + specific editors
ai-toolkit update --local                         # auto-detects editors

Plugin Management

ai-toolkit plugin list                            # show available packs
ai-toolkit plugin install --editor all --all      # install all for Claude + Codex
ai-toolkit plugin status --editor all             # show what's installed

Install Profiles

ai-toolkit install --profile minimal    # agents + skills only
ai-toolkit install --profile standard   # full install (default)
ai-toolkit install --profile strict     # full + git hooks

Verify & Repair

ai-toolkit validate          # check integrity
ai-toolkit doctor --fix      # auto-repair

See CLI Reference for all commands and options.

Platform Support

| Platform | Config Files | Scope | |----------|-------------|-------| | Claude Code | ~/.claude/ | global | | Cursor | .cursor/rules/*.mdc + .cursor/mcp.json | project (~/.cursor/mcp.json for MCP only) | | Windsurf | ~/.codeium/.../global_rules.md + .windsurf/rules/*.md | global + project | | Gemini CLI | ~/.gemini/GEMINI.md | global | | GitHub Copilot | .github/copilot-instructions.md | project | | Cline | ~/Documents/Cline/Rules/*.md + .clinerules/*.md | global + project | | Roo Code | ~/.roo/rules/*.md + .roomodes + .roo/rules/*.md | global rules + project | | Aider | ~/.aider.conf.yml + .aider.conf.yml + CONVENTIONS.md | global + project | | Augment | ~/.augment/rules/*.md + .augment/rules/ai-toolkit-*.md | global + project | | Google Antigravity | .agent/rules/*.md + .agent/workflows/*.md | project | | Codex CLI | AGENTS.md + .agents/rules/*.md + .agents/skills/* + .codex/hooks.json | project + global plugin | | opencode | AGENTS.md + .opencode/{agents,commands,plugins}/* + opencode.json | project + global (~/.config/opencode/) |

Claude Code is always installed (primary platform). Other editors on demand with --editors. All platforms receive the same agent/skill catalog, guidelines, and registered custom rules.

What You Get

| Component | Count | Description | |-----------|-------|-------------| | skills/ (task) | 32 | Slash commands: /commit, /build, /deploy, /test, /mcp-builder, ... | | skills/ (hybrid) | 30 | Slash commands with agent knowledge base | | skills/ (knowledge) | 45 | Domain knowledge auto-loaded by agents (includes 13 <lang>-rules skills) | | agents/ | 44 | Specialized agents across 10 categories | | hooks/ | 22 global + 5 skill-scoped | Quality gates, path safety, prompt governance, session lifecycle | | plugins/ | 11 packs | Opt-in domain bundles (security, research, frontend, enterprise, 6 language packs) | | constitution.md | 6 articles | Machine-enforced safety rules | | rules/ | auto-injected | Language-specific and custom rules injected into your configs | | kb/ | reference docs | Architecture, procedures, and best practices |

Architecture

ai-toolkit/
├── app/
│   ├── agents/          # 44 agent definitions
│   ├── skills/          # 107 skills (task / hybrid / knowledge)
│   ├── rules/           # Auto-injected into your CLAUDE.md
│   ├── hooks/           # Hook scripts (28 entries, 14 lifecycle events)
│   ├── plugins/         # 11 experimental plugin packs (opt-in)
│   ├── output-styles/   # System prompt output style overrides
│   ├── constitution.md  # 6 immutable safety articles
│   └── ARCHITECTURE.md  # Full system design
├── kb/                  # Reference docs, procedures, plans
├── scripts/             # Validation, install, evaluation scripts
├── tests/               # Bats test suite (1131 tests)
└── CHANGELOG.md

Distribution: Symlink-based for agents/skills, copy-based for hooks. Run ai-toolkit update after npm install — all projects pick up changes instantly. See Distribution Model.

Key Features

Machine-enforced constitution — 6-article safety constitution enforced via PreToolUse hooks that actually block rm -rf, DROP TABLE, and irreversible operations. Not just documentation.

28 lifecycle hooks — Executable scripts across 14 events (SessionStart → SessionEnd, plus InstructionsLoaded + ConfigChange). Guards, governance, quality gates, session persistence, MCP health checks, revert protection, test-cohesion enforcement, search-first discipline. See Hooks Catalog.

Security scanning — /skill-audit for code-level risks, /cve-scan for dependency CVEs. Both CI-ready with exit codes.

Iron Law enforcement — /tdd, debugging-tactics, and verification-before-completion enforce non-negotiable gates with anti-rationalization tables. 15 skills total include rationalization resistance.

Multi-language quality gates — Stop hook runs lint + type checks across Python, TypeScript, PHP, Dart, Go after every response.

Agent verification checklists — 10 agents include exit criteria that must be met before presenting results.

Two-stage review — /subagent-development runs Implementer → Spec Review → Quality Review per task.

Persistent memory — memory-pack plugin: SQLite + FTS5 search across past sessions.

Local product telemetry — ai-toolkit stats --summary reports total invocations, skill coverage, unused catalog skills, recent activity, and top skills from local usage data.

Persona presets — 4 roles (backend-lead, frontend-lead, devops-eng, junior-dev) adjust style and priorities.

Config inheritance — Enterprise extends system with constitution immutability and enforcement constraints. See Enterprise Config Guide.

70 language rules — 13 languages + common, 5 categories each. Auto-detected or explicit --lang. See Language Rules.

26 MCP templates — Ready-to-use configs for GitHub, PostgreSQL, Slack, Jira, Sentry, and more. See MCP Templates.

See Unique Features for detailed descriptions of all differentiators.

Key Slash Commands

| Command | Purpose | Effort | |---------|---------|--------| | /workflow <type> | Pre-defined multi-agent workflow (15 types) | max | | /orchestrate | Custom multi-agent coordination (3–6 agents) | max | | /swarm | Parallel Agent Teams: map-reduce, consensus, relay | max | | /plan | Implementation plan with task breakdown | high | | /review | Code review: quality, security, performance | high | | /debug | Systematic debugging with diagnostics | medium | | /refactor | Safe refactoring with pattern analysis | high | | /tdd | Test-driven development with red-green-refactor | high | | /commit | Structured commit with linting | medium | | /pr | Pull request with generated checklist