ai-toolkit

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

What's New in v4.25.1

v4.25.1 fixes the CVE scanner path exercised by the published-package smoke test:

• Legacy npm audit advisories are normalized alongside the modern vulnerabilities response.
• HIGH advisories now produce findings and the documented non-zero exit code instead of a false clean result.
• The post-release scanner fixture now exercises accessibility, SEO, HIPAA, and a deliberately vulnerable npm dependency with their real CLI flags.

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 109 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 Code + Codex
ai-toolkit plugin status --editor all             # show what's installed

Claude Chat / Desktop / Cowork

The Claude app does not read Claude Code's ~/.claude/rules/ or CLAUDE.md. Export and upload the app-native plugin instead:

ai-toolkit claude-app export --verify
# Claude > Customize > Plugins > + > Upload plugin
# Paste the generated *-global-instructions.md into:
# Settings > Cowork > Global instructions

Re-export and re-upload after toolkit or registered-rule updates. Skills work in Chat and Cowork; hooks and sub-agents are active only in Cowork.

Native Codex Plugin

Build or validate the marketplace-ready Codex package without changing ~/.agents or ~/.codex:

ai-toolkit codex-plugin export --output ai-toolkit-codex-plugin.zip
ai-toolkit codex-plugin verify

Extract the ZIP into a local marketplace under plugins/ai-toolkit/, add that marketplace with codex plugin marketplace add <marketplace-root>, then install from /plugins in Codex CLI and start a new session. Review and trust the bundled hooks before use. The ZIP includes plugin-local persona definitions, the briefing helper, the skill-audit helper and its local imports, and other referenced skill resources. Export rejects symlinked output paths and ancestors. Codex IDE does not support plugins.

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 | Hooks | Scope | |----------|-------------|:-----:|-------| | Claude Code | ~/.claude/agents, ~/.claude/skills, ~/.claude/rules/*.md, ~/.claude/settings.json | ✅ | global | | Claude Chat / Cowork | uploaded plugin ZIP + UI global/folder instructions | Cowork only | account/app | | Cursor | .cursor/rules/*.mdc + .cursor/mcp.json + .cursor/skills/* | ✅ | project (~/.cursor/mcp.json for MCP only) | | Windsurf (Devin Desktop) | ~/.config/devin/AGENTS.md + .devin/rules/*.md + .devin/hooks.v1.json + .windsurf/skills/* | ✅ | global + project | | Gemini CLI | ~/.gemini/GEMINI.md + .gemini/settings.json + .gemini/{commands,skills,agents}/ | ✅ | project + user | | GitHub Copilot | Project: AGENTS.md + .github/copilot-instructions.md + .github/{instructions,prompts,agents,skills,hooks}/ + .github/mcp.json; user: $COPILOT_HOME/copilot-instructions.md + $COPILOT_HOME/{instructions,agents,skills,hooks}/ + $COPILOT_HOME/mcp-config.json | ✅ | project + user | | Cline | Project: .cline/{rules,hooks,skills}/ + .clinerules/{hooks,workflows}/; user: ~/.cline/{rules,hooks,skills}/ + ~/Documents/Cline/{Rules,Hooks}/ compatibility | ✅ | global + project | | Roo Code / Zoo 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 | Project .agents/{rules,workflows,skills,agents,hooks}/; user ~/.gemini/config/{skills,agents,hooks}/; opt-in native plugin export | ✅ | project + user | | Codex CLI | Project: AGENTS.md + .agents/skills/* + .codex/{agents,hooks}/ + .codex/{hooks.json,config.toml}; user: $CODEX_HOME/{AGENTS.md,agents,hooks.json,config.toml} + $HOME/.agents/skills/* | ✅ | project + user | | opencode | AGENTS.md + .opencode/{agents,commands,plugins,skills}/* + opencode.{json,jsonc} | ✅ | project + global (~/.config/opencode/) |

Claude Code is always installed (primary platform). Other editors are selected with --editors; the Claude app uses the separate claude-app export flow because its customization store is UI/plugin-managed. The Hooks column marks platforms with lifecycle enforcement. Platforms marked — receive guidance without blocking hooks.

What You Get

| Component | Count | Description | |-----------|-------|-------------| | skills/ (task) | 32 | Slash commands: /commit, /build, /deploy, /test, /mcp-builder, ... | | skills/ (hybrid) | 31 | Slash commands with agent knowledge base | | skills/ (knowledge) | 46 | Domain knowledge auto-loaded by agents (includes 13 <lang>-rules skills) | | agents/ | 44 | Specialized agents across 10 categories | | hooks/ | 28 entries / 14 events + statusLine | Quality gates, path safety, prompt governance, loop guard, session lifecycle | | plugins/ | 2 packs | Opt-in packs that install files of their own (memory, enterprise) | | constitution.md | 7 articles | Machine-enforced safety rules | | rules/ | auto-synced | Global/project rule files for Claude and other editors | | kb/ | reference docs | Architecture, procedures, and best practices |

Architecture

ai-toolkit/
├── app/
│   ├── agents/          # 44 agent definitions
│   ├── skills/          # 109 skills (task / hybrid / knowledge)
│   ├── rules/           # Source rules synced into Claude/editor rule files
│   ├── hooks/           # Hook scripts (29 entries, 14 lifecycle events)
│   ├── claude-app/      # Generated Chat/Cowork plugin rules, hooks, instructions
│   ├── plugins/         # 2 experimental plugin packs (opt-in)
│   ├── output-styles/   # System prompt output style overrides
│   ├── constitution.md  # 7 immutable safety articles
│   └── ARCHITECTURE.md  # Full system design
├── kb/                  # Reference docs, procedures, plans
├── scripts/             # Validation, install, evaluation scripts
├── tests/               # Bats and Python test suite (1637 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 — 7-article safety constitution enforced via PreToolUse hooks that actually block rm -rf, DROP TABLE, and irreversible operations. Not just documentation.

28 lifecycle hook entries: Executable handlers across 14 events (SessionStart → SessionEnd, plus InstructionsLoaded + ConfigChange). Guards, governance, quality gates, session persistence, MCP health checks, revert protection, test-cohesion enforcement, loop guard, and 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 | medium | | /docs | Generate README, API docs, architecture notes | high | | /explore | Interactive codebase visualization | medium | | /write-a-prd | Create PRD through interactive interview | high | | /prd-to-plan | Convert PRD into vertical-slice implementation plan | high | | /design-an-interface | Generate 3+ radically different interface designs | high | | /grill-me | Stress-test a plan through Socratic questioning | medium | | /triage-issue | Triage bug with deep investigation and TDD fix plan | high | | /architecture-audit | Discover shallow modules, propose refactors | high | | /council | 4-perspective decision evaluation | high | | /cve-scan | Scan dependencies for known CVEs | medium | | /skill-audit | Scan skills/agents for security risks | medium | | /repeat | Autonomous loop with safety controls | medium | | /persona | Switch engineering persona at runtime | low |

/workflow Types

feature-development    backend-feature       frontend-feature
api-design             database-evolution    test-coverage
security-audit         codebase-onboarding   spike
debugging              incident-response     performance-optimization
infrastructure-change  application-deploy    proactive-troubleshooting

Multi-Agent Skill Selection

Need multi-agent coordination?
├── Know your domains? → /orchestrate (ad-hoc, 3-6 agents)
├── Have a known pattern? → /workflow <type> (15 templates)
├── Need consensus/map-reduce? → /swarm <mode>
├── Want Agent Teams API? → /teams (experimental)
└── Executing a plan? → /subagent-development

Getting Started

1. Customize CLAUDE.md — add your project's tech stack, commands, and conventions at the top (above toolkit markers).

2. Start using skills:

   /onboard     # guided setup interview
   /explore     # understand your codebase
   /plan        # plan a feature

3. Verify your install:

   ai-toolkit validate

Documentation

| Topic | Link | |-------|------| | CLI Reference | kb/reference/cli-reference.md | | Unique Features | kb/reference/unique-features.md | | Architecture Overview | kb/reference/architecture-overview.md | | Hooks Catalog | kb/reference/hooks-catalog.md | | Language Rules | kb/reference/language-rules.md | | MCP Templates | kb/reference/mcp-templates.md | | Extension API | kb/reference/extension-api.md | | Manifest Install | kb/reference/manifest-install.md | | Plugin Packs | kb/reference/plugin-pack-conventions.md | | Enterprise Config | kb/reference/enterprise-config-guide.md | | Distribution Model | kb/reference/distribution-model.md | | Ecosystem Comparison | kb/reference/comparison.md | | Codex CLI Compatibility | kb/reference/codex-cli-compatibility.md | | opencode Compatibility | kb/reference/opencode-compatibility.md | | GitHub Copilot Compatibility | kb/reference/copilot-compatibility.md | | Maintenance SOP | kb/procedures/maintenance-sop.md |

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md for responsible disclosure policy.

License

Apache License 2.0 — see LICENSE and NOTICE.

Fork it, modify it, ship it commercially. Three things the licence asks in return:

• Keep the attribution. Redistributions must carry the contents of NOTICE (§4d) — that is where the project name, copyright and source URL live.
• Say what you changed. Modified files must carry a prominent notice stating that you changed them (§4b).
• Names are not included. The licence grants no rights to the "ai-toolkit" or "SoftSpark" names or marks (§6).

Releases up to and including v4.20.0 were published under MIT and stay available under MIT; the change applies going forward and revokes nothing already granted. Contributions received while the project was MIT-licensed remain their authors' copyright and are redistributed under Apache 2.0 with the original MIT notice preserved in NOTICE, as MIT requires.

Changelog

See CHANGELOG.md.

Extracted from production use at SoftSpark. Built to be the toolkit we wished existed.