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.23.0

v4.23.0 — hipaa-validate scanned a project without a manifest silently clean: its language-tagged patterns never ran, and the report said HIGH: 0. Zero reads as compliant. Detection now falls back to file extensions, the summary says how the language was decided, and an undecidable run warns that a zero means unscanned. Manifest-declaring projects are unaffected. Found by the post-release SOP, not by a user.

What's New in v4.22.1

v4.22.1 — nine skills, not four, could not find their own scripts. v4.22.0 grepped for one spelling of the bug and missed five more, a .py file run through bash, and a script that crashed on --help. validate.py now fails the build on the entire class, and the post-release SOP runs every skill's documented command from the installed copy — which is how these were found.

What's New in v4.22.0

v4.22.0 turns compatibility promises into tests, and makes two validator skills actually run the scanners they ship.

• The public surface is checked, not documented. app/surface.json pins 275 entries — skills, agents, frontmatter fields, CLI commands, hook scripts and events, KB categories, plugin packs. Removing any of them fails npm test. Adding is free: a surface nobody has installed has no users to break. BACKWARD_COMPATIBILITY.md says which surfaces are load-bearing and how to deprecate one properly.
• a11y-validate and seo-validate shipped scanners that nothing invoked. 1,196 lines of working Python sat on disk while the model was told to grep the pattern tables by hand. Both now run their script for a deterministic baseline, then take an explicit manual pass — with a measured coverage table saying which criteria the script handles and which are yours.
• /brainstorm — the first planning skill allowed to conclude "do not build this". Every other one produces an artifact; a pipeline that cannot say no is a yes-machine.
• Skill bodies have a budget. Error above 20,000 bytes, warn above 18,000, headroom printed every run. Three validator skills were split into reference/, taking 47 KB off the hot path, with scripts/check_split.py proving nothing was lost.
• Four skills invoked their scripts through a path that never resolved. $(dirname "$0") expands to the shell's directory, not the skill's.

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.

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	✅	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 / 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	.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 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 (1494 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.