Professional-grade AI coding toolkit with multi-platform support. Machine-enforced safety, 108 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.
v4.15.1 fixes Copilot project upgrades and profile downgrades that could leave obsolete toolkit instructions, prompts, and hooks active.
- Complete legacy cleanup: byte-exact generated files from v3.0.0 through v4.14.1 are recognized and removed when switching a project to
minimal. - No user-file deletion: unmarked prompts and instructions that do not match a historical toolkit artifact remain untouched.
- Race-safe removal: managed cleanup uses pinned directory descriptors and transactional rollback instead of path-based deletion.
See CHANGELOG.md for full history.
- Install
- Platform Support
- What You Get
- Architecture
- Key Features
- Key Slash Commands
- Getting Started
- Documentation
- Contributing
- Security
- License
- Changelog
# 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 installThat's it. Claude Code picks up 108 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.
npm install -g @softspark/ai-toolkit@latest && ai-toolkit updatecd 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 editorsai-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 installedThe 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 instructionsRe-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.
ai-toolkit install --profile minimal # agents + skills only
ai-toolkit install --profile standard # full install (default)
ai-toolkit install --profile strict # full + git hooksai-toolkit validate # check integrity
ai-toolkit doctor --fix # auto-repairSee CLI Reference for all commands and options.
| 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 |
✅ | global |
| 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 | ~/Documents/Cline/Rules/*.md + ~/.cline/skills/* + .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 | .agents/rules/*.md + .agents/workflows/*.md + skill pointer in .agent/skills/* (IDE) and .agents/skills/* (CLI) |
— | project |
| 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}/* + opencode.json |
✅ | project + global (~/.config/opencode/) |
Claude Code is always installed (primary platform). Other editors are selected with
--editors; the Claude app uses the separateclaude-app exportflow because its customization store is UI/plugin-managed. The Hooks column marks platforms with lifecycle enforcement. Platforms marked — receive guidance without blocking hooks.
| 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) |
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/ |
11 packs | Opt-in domain bundles (security, research, frontend, enterprise, 6 language packs) |
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 |
ai-toolkit/
├── app/
│ ├── agents/ # 44 agent definitions
│ ├── skills/ # 108 skills (task / hybrid / knowledge)
│ ├── rules/ # Source rules synced into Claude/editor rule files
│ ├── hooks/ # Hook scripts (28 entries, 14 lifecycle events)
│ ├── claude-app/ # Generated Chat/Cowork plugin rules, hooks, instructions
│ ├── plugins/ # 11 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 test suite (1377 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.
Machine-enforced constitution — 7-article safety constitution enforced via PreToolUse hooks that actually block rm -rf, DROP TABLE, and irreversible operations. Not just documentation.
29 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, loop guard, 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.
| 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 |
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
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
-
Customize CLAUDE.md — add your project's tech stack, commands, and conventions at the top (above toolkit markers).
-
Start using skills:
/onboard # guided setup interview /explore # understand your codebase /plan # plan a feature -
Verify your install:
ai-toolkit validate
| 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 |
See CONTRIBUTING.md.
See SECURITY.md for responsible disclosure policy.
MIT — see LICENSE.
See CHANGELOG.md.
Extracted from production use at SoftSpark. Built to be the toolkit we wished existed.