# AI Toolkit Architecture

Universal multi-agent system for software development. Works across all repositories.

## Quick Stats

| Component | Count |
|-----------|-------|
| Agents | See agents catalog |
| Skills | See skills catalog |
| Hooks | 14 events / 29 entries (SessionStart ×2, Notification ×1, PreToolUse ×5, UserPromptSubmit ×2, PostToolUse ×6, Stop ×4, TaskCompleted ×1, TeammateIdle ×1, SubagentStart ×1, SubagentStop ×1, PreCompact ×2, SessionEnd ×1, InstructionsLoaded ×1, ConfigChange ×1) plus statusLine |

---

## Layered Model (the five-layer mental model)

The toolkit is organised as five stacked layers. Higher layers depend on lower layers, never the other way around. Treat this as the canonical mental model when adding features — pick the lowest layer that fits.

```
┌─────────────────────────────────────────────────────────────┐
│  Layer 5 — Plugins (distribution)                           │
│  Bundles for npm / Claude app / marketplace / eject         │
│  Files: app/claude-app/, app/plugins/, plugin.json          │
├─────────────────────────────────────────────────────────────┤
│  Layer 4 — Subagents (delegation)                           │
│  Specialised personas spawned via Agent / Teams             │
│  Files: app/agents/, .claude/agents/                        │
├─────────────────────────────────────────────────────────────┤
│  Layer 3 — Hooks (the guardrail layer)                      │
│  Lifecycle events: SessionStart, PreToolUse, Stop, …        │
│  Files: app/hooks/*.sh, settings.json hooks block           │
├─────────────────────────────────────────────────────────────┤
│  Layer 2 — Skills (the knowledge layer)                     │
│  Slash-commands, knowledge skills, hybrid skills            │
│  Files: app/skills/<name>/SKILL.md                          │
├─────────────────────────────────────────────────────────────┤
│  Layer 1 — CLAUDE.md (the memory layer)                     │
│  Persistent rules + auto-memory loaded into every session   │
│  Files: CLAUDE.md (global / project / .claude)              │
└─────────────────────────────────────────────────────────────┘
```

### Where does my new feature go?

| If the feature is… | Add it at | Examples |
|---|---|---|
| A persistent rule the model must always know | Layer 1 (CLAUDE.md) | "always sync_tasks first", commit conventions |
| A reusable workflow / domain knowledge | Layer 2 (Skills) | `/debug`, `/review`, `python-rules` |
| Behavior the harness must enforce automatically | Layer 3 (Hooks) | block destructive `rm -rf`, run lint on Stop |
| A specialised role for delegation | Layer 4 (Subagents) | `security-auditor`, `database-architect` |
| A shippable bundle for other repos or Claude app | Layer 5 (Plugins) | `app/plugins/`, `app/claude-app/` |

### Cross-cutting rules

- A skill MAY trigger an agent (`agent: <name>` frontmatter) — that's Layer 2 calling Layer 4.
- A hook MUST NOT call a skill — hooks are deterministic shell, skills are LLM-driven.
- A plugin MAY bundle skills + agents + hooks, but never the inverse.
- Claude Code reads CLAUDE.md across layers. Claude Chat/Cowork uses app-global/folder instructions and plugin skills instead; `ai-toolkit claude-app export` (backed by `claude_app.py`) builds the uploadable plugin ZIP + Cowork global-instructions and renders core rules into `ai-toolkit-rules` for that runtime.

---

## Agents

### Orchestration & Planning (4)
| Agent | Model | Purpose |
|-------|-------|---------|
| `orchestrator` | opus | Multi-agent coordination, minimum 3 agents per task |
| `project-planner` | opus | Task breakdown, plan creation |
| `product-manager` | opus | Requirements, user stories, PRDs, backlog prioritization |
| `tech-lead` | opus | Code quality authority, architecture patterns, stack decisions |

### Development (5)
| Agent | Model | Purpose |
|-------|-------|---------|
| `backend-specialist` | opus | Node.js, Python, PHP, APIs |
| `frontend-specialist` | opus | React, Next.js, Vue, Nuxt |
| `mobile-developer` | opus | React Native, Flutter, native |
| `game-developer` | opus | Unity, Godot, Unreal, Phaser |
| `database-architect` | opus | Schema design, migrations, query optimization, operations |

### AI/ML (6)
| Agent | Model | Purpose |
|-------|-------|---------|
| `ai-engineer` | opus | LLM integration, vector search, RAG pipelines |
| `ml-engineer` | opus | Model training, MLOps |
| `nlp-engineer` | opus | NLP pipelines, text processing |
| `data-scientist` | opus | Statistics, analysis, visualization |
| `data-analyst` | sonnet | SQL, analytics, reporting |
| `prompt-engineer` | opus | Prompt design, optimization |

### Quality & Security (6)
| Agent | Model | Purpose |
|-------|-------|---------|
| `code-reviewer` | opus | Code review, standards |
| `test-engineer` | opus | Test strategy, implementation |
| `qa-automation-engineer` | opus | E2E, API, performance testing |
| `security-auditor` | opus | Security audit, pen testing, OWASP, vulnerability assessment |
| `security-architect` | opus | Threat modeling, secure design, AuthN/AuthZ |
| `system-governor` | opus | Constitution guardian, VETO power |

### Infrastructure & DevOps (6)
| Agent | Model | Purpose |
|-------|-------|---------|
| `devops-implementer` | opus | CI/CD, automation |
| `infrastructure-architect` | opus | Cloud architecture, IaC |
| `infrastructure-validator` | sonnet | Infrastructure validation |
| `incident-responder` | sonnet | Incident management |
| `performance-optimizer` | opus | Performance tuning |
| `llm-ops-engineer` | opus | LLM operations, monitoring |

### Research & Documentation (5)
| Agent | Model | Purpose |
|-------|-------|---------|
| `explorer-agent` | sonnet | Codebase discovery (READ-ONLY) |
| `technical-researcher` | opus | Deep technical investigation, research synthesis |
| `search-specialist` | sonnet | Search optimization |
| `fact-checker` | sonnet | Verification, source checking |
| `documenter` | sonnet | Documentation, KB management, SOPs, API docs |

### Management & Evolution (4)
| Agent | Model | Purpose |
|-------|-------|---------|
| `chief-of-staff` | sonnet | Executive summaries, daily briefings |
| `meta-architect` | opus | Self-optimization, agent definition updates |
| `predictive-analyst` | sonnet | Impact prediction, regression forecasting |
| `business-intelligence` | sonnet | Opportunity discovery, KPI gaps |

### Autonomous (2)
| Agent | Model | Purpose |
|-------|-------|---------|
| `night-watchman` | sonnet | Autonomous maintenance: dependency updates, dead code |
| `chaos-monkey` | opus | Resilience testing: fault injection, failure verification |

### MCP (2)
| Agent | Model | Purpose |
|-------|-------|---------|
| `mcp-specialist` | opus | MCP server design, client config, troubleshooting |
| `mcp-testing-engineer` | sonnet | MCP testing |

### Specialist (4)
| Agent | Model | Purpose |
|-------|-------|---------|
| `debugger` | opus | Bug investigation, root cause |
| `code-archaeologist` | sonnet | Legacy code investigation |
| `command-expert` | sonnet | CLI, bash, automation |
| `seo-specialist` | sonnet | SEO optimization |

---

## Skills

### Task Skills (32)
| Skill | Slash Command | Purpose |
|-------|---------------|---------|
| `commit` | `/commit` | Create well-structured git commits (Conventional Commits) |
| `pr` | `/pr` | Create GitHub pull request with template and checks |
| `test` | `/test` | Run tests (pytest, vitest, phpunit, flutter, go, cargo) |
| `build` | `/build` | Build project (auto-detects type) |
| `lint` | `/lint` | Run linting and type checking |
| `fix` | `/fix` | Auto-fix failing tests or lint errors |
| `deploy` | `/deploy` | Deploy to target environment with pre-checks |
| `rollback` | `/rollback` | Safe rollback (git, database, deployment) |
| `migrate` | `/migrate` | Database migration workflow |
| `ci` | `/ci` | Generate/manage CI/CD pipeline configuration |
| `panic` | `/panic` | Emergency halt all autonomous operations |
| `index` | `/index` | Reindex knowledge base with change detection |
| `onboard` | `/onboard` | Guided project setup with the toolkit |
| `night-watch` | `/night-watch` | Trigger autonomous maintenance cycle |
| `evolve` | `/evolve` | Trigger meta-architect self-optimization |
| `chaos` | `/chaos` | Run chaos engineering experiment |
| `predict` | `/predict` | Analyze code changes for impact and risks |
| `biz-scan` | `/biz-scan` | Scan for business value opportunities |
| `briefing` | `/briefing` | Generate executive summary of system status |
| `evaluate` | `/evaluate` | Evaluate RAG quality |
| `health` | `/health` | Health check (auto-detect services) |
| `skill-creator` | `/skill-creator` | Create new skills following Agent Skills standard |
| `hook-creator` | `/hook-creator` | Create new hooks with guided workflow and validation |
| `command-creator` | `/command-creator` | Create new slash commands with frontmatter and workflow guidance |
| `agent-creator` | `/agent-creator` | Create new specialized agents with tools and trigger guidance |
| `plugin-creator` | `/plugin-creator` | Create experimental opt-in plugin packs with manifests, conventions, and optional modules |
| `prd-to-issues` | `/prd-to-issues` | Break PRD into GitHub issues with vertical slices and HITL/AFK tagging |
| `skill-audit` | `/skill-audit` | Scan skills and agents for security risks, dangerous patterns, secrets |
| `hipaa-validate` | `/hipaa-validate` | Scan codebase for HIPAA compliance: PHI exposure, missing audit logging, unencrypted transmission/storage, access control gaps, temp file exposure, missing BAA references |
| `mcp-builder` | `/mcp-builder` | Build production-grade MCP servers using 4-phase methodology (research, implement, test, evaluate) |

### Hybrid Skills (31)
| Skill | Slash Command | Purpose |
|-------|---------------|---------|
| `explore` | `/explore` | Codebase exploration and tech stack discovery |
| `debug` | `/debug` | Systematic debugging with logs and diagnostics |
| `review` | `/review` | Code review for quality, security, performance |
| `plan` | `/plan` | Create structured plan with task breakdown |
| `refactor` | `/refactor` | Plan and execute code refactoring with safety checks |
| `analyze` | `/analyze` | Analyze code quality, complexity, and patterns |
| `cve-scan` | `/cve-scan` | Scan project dependencies for CVEs using native tools (npm, pip, composer, cargo, go, ruby, dart) |
| `docs` | `/docs` | Generate/update documentation (README, API docs, architecture notes) |
| `search` | `/search` | Search knowledge base (MCP + local fallback) |
| `explain` | `/explain` | Explain file/module architecture with Mermaid diagrams |
| `orchestrate` | `/orchestrate` | Multi-agent coordination for complex tasks |
| `swarm` | `/swarm` | Massive parallelism via Agent Teams |
| `workflow` | `/workflow` | Run agent workflow |
| `instinct-review` | `/instinct-review` | Review, curate, and manage learned instincts |
| `write-a-prd` | `/write-a-prd` | Create PRD through interactive interview and module design |
| `prd-to-plan` | `/prd-to-plan` | Convert PRD into phased vertical-slice implementation plan |
| `tdd` | `/tdd` | Test-driven development with red-green-refactor loop |
| `design-an-interface` | `/design-an-interface` | Generate 3+ radically different interface designs |
| `grill-me` | `/grill-me` | Stress-test a plan through relentless Socratic questioning |
| `ubiquitous-language` | `/ubiquitous-language` | Extract DDD-style ubiquitous language glossary |
| `refactor-plan` | `/refactor-plan` | Create detailed refactor plan with tiny commits |
| `qa-session` | `/qa-session` | Interactive QA session with GitHub issue filing |
| `triage-issue` | `/triage-issue` | Triage bug with deep investigation and TDD fix plan |
| `architecture-audit` | `/architecture-audit` | Discover shallow modules and propose deepening refactors |
| `subagent-development` | `/subagent-development` | Execute plans with 2-stage review (spec + quality) per task |
| `repeat` | `/repeat` | Autonomous loop with safety controls (Ralph Wiggum pattern) |
| `mem-search` | `/mem-search` | Search past coding sessions via natural language (memory-pack) |
| `persona` | `/persona` | Switch engineering persona at runtime (backend-lead, frontend-lead, devops-eng, junior-dev) |
| `council` | `/council` | 4-perspective decision evaluation (Advocate, Critic, Pragmatist, User-Proxy) with synthesis |
| `introspect` | `/introspect` | Agent self-debugging: classify failure pattern, suggest recovery action, emit introspection report |

### Knowledge Skills - Development (16)
| Skill | Purpose |
|-------|---------|
| `app-builder` | Project scaffolding, tech stack |
| `api-patterns` | REST, GraphQL, JSON-RPC |
| `database-patterns` | Schema, queries, migrations |
| `flutter-patterns` | Flutter/Dart patterns |
| `ecommerce-patterns` | Magento, PrestaShop, etc. |
| `clean-code` | Multi-language code quality principles |
| `typescript-patterns` | TypeScript/JavaScript patterns for frontend and backend |
| `design-engineering` | UI polish, animation craft, easing, transforms, accessibility |
| `documentation-standards` | KB document conventions, frontmatter spec, category taxonomy |
| `rust-patterns` | Ownership, borrowing, Cargo, tokio, serde |
| `java-patterns` | Records, sealed classes, Spring Boot, JUnit 5 |
| `csharp-patterns` | Nullable refs, async/await, ASP.NET Core, EF Core |
| `kotlin-patterns` | Coroutines, DSLs, sealed classes, Ktor, MockK |
| `swift-patterns` | Protocol-oriented, SwiftUI, async/await, SPM |
| `ruby-patterns` | Blocks, Rails conventions, RSpec, ActiveRecord |
| `brand-voice` | Anti-trope list, voice principles, LLM rhetoric prevention |

### Knowledge Skills - Infrastructure (6)
| Skill | Purpose |
|-------|---------|
| `docker-devops` | Docker, CI/CD |
| `security-patterns` | Auth, validation, security |
| `ci-cd-patterns` | GitHub Actions, GitLab CI, Kubernetes |
| `observability-patterns` | Logging, metrics, tracing, monitoring |
| `testing-patterns` | Multi-language testing strategies |
| `migration-patterns` | Database & API migration patterns |

### Knowledge Skills - AI/RAG (6)
| Skill | Purpose |
|-------|---------|
| `rag-patterns` | RAG, retrieval optimization |
| `mcp-patterns` | MCP server patterns |
| `prompt-caching-patterns` | Anthropic prompt caching: TTL, breakpoints, hit rate |
| `json-mode-patterns` | Structured JSON output via tool-use forcing |
| `content-moderation-patterns` | Two-stage moderation: pre-filter + LLM classifier |
| `model-routing-patterns` | Haiku/Sonnet/Opus routing, escalation, fallback |

### Knowledge Skills - Process (5)
| Skill | Purpose |
|-------|---------|
| `git-mastery` | Safe history rewriting, bisect, complex merges |
| `architecture-decision` | Trade-off analysis, architecture note templates |
| `performance-profiling` | CPU, memory, I/O, database bottleneck profiling |
| `research-mastery` | Hierarchy of Truth protocol |
| `verification-before-completion` | Iron Law: evidence-before-claims, no completion without fresh verification |

---

## Orchestration Model

### 2-Phase Orchestration
```
Phase 1: PLANNING
├── Decompose task
├── Select agents (minimum 3)
├── Create dependencies
└── USER CHECKPOINT <- Approval required

Phase 2: IMPLEMENTATION
├── Execute in dependency order
├── Collect results
└── Generate report
```

### Agent Selection Matrix
| Task Type | Primary | Supporting |
|-----------|---------|------------|
| New Feature | backend/frontend | test-engineer, code-reviewer |
| Bug Fix | debugger | backend/frontend, test-engineer |
| Performance | performance-optimizer | database-architect |
| Security | security-auditor | code-reviewer |
| Research | technical-researcher | search-specialist, fact-checker |
| Documentation | documenter | explorer-agent |

---

## Directory Structure

```
.claude/
├── ARCHITECTURE.md      # This file
├── agents/              # Agent definitions
├── hooks.json           # Quality gate hooks (multi-language)
├── skills/              # All skills: task, hybrid, knowledge
├── output-styles/       # System prompt output style overrides (e.g. golden-rules)
├── constitution.md      # Immutable safety rules (7 articles)
└── settings.local.json  # Local settings + Agent Teams config
```

---

## Agent Teams Mode (Native Parallelism)

When `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` is enabled:

```
Lead Session (You)
├── Teammate 1 (security-auditor) -> tmux pane 1
├── Teammate 2 (backend-specialist) -> tmux pane 2
├── Teammate 3 (test-engineer) -> tmux pane 3
└── Shared Task List
```

### Quality Hooks (`.claude/settings.json` → `hooks`)
| Hook | Trigger | Action |
|------|---------|--------|
| `SessionStart` | Session begins | Loads session context + active instincts |
| `PreToolUse` | Before Bash execution | Guards against destructive commands |
| `PreToolUse` | Before file ops (Read/Edit/Write/Glob/Grep) | Guards against wrong-user path hallucination |
| `UserPromptSubmit` | Before prompt execution | Prompt governance reminder |
| `UserPromptSubmit` | Before prompt execution | Usage tracking (skill invocations) |
| `PostToolUse` | After edit/write tools | Lightweight validation reminder |
| `PostToolUse` | After search tools | Clears the per-session search-first flag |
| `PostToolUse` | After successful Bash tools | Observes or safely replaces eligible text output after exact recovery is stored; Claude Code only |
| `Stop` | After Claude response | Multi-language quality check + saves session context |
| `Stop` | After Claude response | Blocks skipped search-first only when a real MCP/Web search provider is configured, with Codex log fallback |
| `TaskCompleted` | Teammate marks task done | Multi-language lint + type check (blocking) |
| `TeammateIdle` | Teammate goes idle | Reminds to verify completeness |
| `SubagentStart` | Subagent starts | Scope reminder for spawned subagents |
| `SubagentStop` | Subagent completes | Handoff checklist for spawned subagents |
| `Notification` | Claude notification | OS notification |
| `PreCompact` | Before compaction | Saves context before compaction boundary |
| `SessionEnd` | Claude session ends | Cleans owned output recovery, then writes the next-session handoff snapshot |

---

## Extension Points

### MCP Templates (26)
`app/mcp-templates/` ships 26 ready-to-use MCP server config templates (filesystems, databases, GitHub, Slack, etc.). Opt-in via `ai-toolkit install --modules mcp-templates` or activated automatically with `--profile strict|full`.

### Language Rules (68 files, 13 languages)
`app/rules/` contains per-language coding rules. Supported languages: TypeScript, Python, Go, Rust, Java, Kotlin, Swift, Dart, C#, PHP, C++, Ruby, and common (shared). Auto-detected from project files via `--auto-detect` or selected with `--modules rules-<lang>`.

Language rules are propagated to **all configured editors** — not just Claude Code. `dir_rules_shared.build_language_rules()` reads `app/rules/<lang>/*.md`, strips frontmatter, and returns combined content per language. Each directory-based generator (Cursor, Devin/Windsurf, Cline, Roo, Augment, Antigravity, Codex) emits `ai-toolkit-lang-<lang>` files in its native format. Claude Chat/Cowork receives the existing language skills plus an app-only `ai-toolkit-rules` skill through `claude_app.py`. Registered custom rules are embedded in the local app bundle and propagated to directory-based editors.

### Codex Integration
Codex receives `AGENTS.md`, `.agents/rules/*.md`, optional `.agents/skills/*`, and `.codex/hooks.json`. `generate_codex_hooks.py` emits only Codex-supported lifecycle events and prefixes commands with `AI_TOOLKIT_HOOK_QUIET=1`, so informational hook output is not shown at session start or prompt submit while side effects and blocking Stop decisions still run. The `UserPromptSubmit` governance hook also sets `AI_TOOLKIT_HOOK_FORMAT=json` so proactive `additionalContext` reaches the model quietly. Claude's bundled `UserPromptSubmit` hook uses the same quiet JSON context path.

### opencode Integration (v2.5.0+)
opencode is the 11th supported editor. Five generators handle its integration surface:

- `generate_opencode.py` → `AGENTS.md` body (shared with Codex; separate marker section prevents clobbering).
- `generate_opencode_agents.py` → `.opencode/agents/ai-toolkit-*.md` (one per ai-toolkit agent, `mode: subagent`).
- `generate_opencode_commands.py` → `.opencode/commands/ai-toolkit-*.md` (one per user-invocable skill, uses required `template: |` field; knowledge-only skills excluded).
- `generate_opencode_plugin.py` → `.opencode/plugins/ai-toolkit-hooks.js` (single named export `AiToolkitHooks`; bridges `session.created`, `session.compacted`, `session.deleted`, `message.updated/part.updated`, `tool.execute.before/after`, `permission.asked`, `command.executed` to the shared Bash hooks in `~/.softspark/ai-toolkit/hooks/` via Bun `$` — script path bound as a JS constant, payload on stdin, no shell interpolation).
- `generate_opencode_json.py` → `opencode.json` MCP merge (translates `.mcp.json` local/remote shapes; preserves user-authored keys; idempotent).

All five generators accept a `config_root` / `output_path` parameter so the same code path handles project-local (`./.opencode/…`) and global (`~/.config/opencode/…`, no `.opencode/` nesting) layouts. Skill adaptation for Claude-only orchestration primitives (`Agent`/`TeamCreate`/`TaskCreate`) is handled by reusing `codex_skill_adapter.py` — opencode, like Codex CLI, lacks these primitives, so the same translation layer applies (no duplication). Global install: `~/.config/opencode/{AGENTS.md,agents/,commands/,plugins/,opencode.json}`. Auto-detection markers: `opencode.json`, `.opencode/`, `.opencode/agents`, `.opencode/commands`.

### Extension API (`inject-hook`, `inject-rule`)
The `inject_section_cli.py` script provides a stable marker-based injection API. Any tool can add sections to `CLAUDE.md`, `constitution.md`, or `ARCHITECTURE.md` without overwriting user content, using `<!-- TOOLKIT:START:<id> -->` / `<!-- TOOLKIT:END:<id> -->` markers. `inject_hook_cli.py` injects hooks into `settings.json` with `_source` tags — supports both local files and HTTPS URLs (cached in `~/.softspark/ai-toolkit/hooks/external/`, auto-refreshed on `update`). Shared URL fetch logic lives in `url_fetch.py`.

### SLM Compilation (`compile-slm`)
`scripts/compile_slm.py` compiles the full toolkit (20K+ tokens) into a minimal system prompt for Small Language Models (2K-16K tokens). Pipeline: Parse → Score → Compress → Pack → Emit. Supports 4 compression levels (ultra-light, light, standard, extended), 4 output formats (raw, ollama, json-string, aider), persona-aware scoring, and language-aware rule filtering. Profile `offline-slm` in `manifest.json`. Constitution is always included (non-negotiable).

### Config Inheritance (`extends`)
`scripts/config_resolver.py`, `config_merger.py`, `config_validator.py`, `config_cli.py`, `config_scaffold.py`, `config_lock.py`. Enterprise configuration inheritance via `.softspark-toolkit.json` `extends` field. Resolves base configs from npm packages, Git URLs, or local paths. Layered deep merge with constitution immutability (Articles I-VII absolute), enforce constraints (`requiredAgents`, `requiredPlugins`, `forbidOverride`, `minHookProfile`), override validation (`override: true` + justification), and a source/version/integrity lock file (`.softspark-toolkit.lock.json`). `requiredPlugins` materializes configuration intent and does not install plugin packs. CLI: `config validate`, `config diff`, `config init`, `config create-base`, `config check`. Integrated into `install --local` and `update --local` flows.

### Project Registry
`scripts/install_steps/project_registry.py`, `scripts/update_projects.py`, `scripts/projects_cli.py`. Tracks all `--local` installed projects in `~/.softspark/ai-toolkit/projects.json`. `ai-toolkit update` propagates to all registered projects in parallel via `ThreadPoolExecutor`. CLI: `ai-toolkit projects`, `--prune`, `remove <path>`.

### Manifest Install (`--modules`, `--auto-detect`)
`manifest.json` defines all installable components as named modules. Install individual modules with `ai-toolkit install --modules <name>` or let the installer detect which language rules to add based on project files (e.g. `package.json` → `rules-typescript`, `go.mod` → `rules-golang`).

---

## Principles

1. **Universal**: No project-specific references
2. **KB-First**: Always search before answering
3. **Multi-Agent**: Minimum 3 agents for complex tasks
4. **2-Phase**: Plan -> Approve -> Implement
5. **Read-Only Exploration**: Explorer agent never writes
6. **Cite Sources**: Always include `[PATH: ...]`
7. **Multi-Language**: All tools, hooks, and skills support multiple tech stacks

---

## Frontmatter Schema (Agent Skills spec + ai-toolkit extensions)

Canonical spec: https://agentskills.io/specification. ai-toolkit is spec-conformant on required fields and adds extensions at the top level for Claude Code integration.

### Spec-defined fields (agentskills.io)

| Field | Required | Constraints |
|-------|----------|-------------|
| `name` | Yes | 1-64 chars, lowercase `a-z0-9` + hyphens, no leading/trailing hyphen, no `--`, must match parent directory |
| `description` | Yes | 1-1024 chars |
| `license` | No | License name or bundled file reference |
| `compatibility` | No | Max 500 chars; environment requirements |
| `metadata` | No | String-keyed map |
| `allowed-tools` | No | Space-separated per spec; ai-toolkit uses comma-separated (see below) |

### ai-toolkit extensions (beyond spec)

These live at the top level for convenience. If a future strict spec parser is adopted, move them under `metadata:`.

| Field | Type | Purpose |
|-------|------|---------|
| `user-invocable` | bool | Surfaces the skill as a slash command. `false` = knowledge skill. |
| `disable-model-invocation` | bool | Task skill flag; prevents auto-invocation by the model. |
| `effort` | enum | `low`/`medium`/`high`/`max` — planner and SLM compiler hint. |
| `agent` | string | Delegates the skill to a specialized agent. |
| `context` | string | `fork` runs the skill in an isolated forked context. |
| `argument-hint` | string | Argument pattern for the CLI (e.g. `[symptom]`). |
| `color` | string | Visual tag for agent cards. |

### `allowed-tools` format note

Spec example uses space separation: `allowed-tools: Bash(git:*) Read`. Claude Code parses several formats leniently: comma-separated, JSON array, and space-separated. **ai-toolkit uses comma-separated** because `scripts/codex_skill_adapter.py:70` and `scripts/audit_skills.py:157` split on `,`. Do not mass-convert unless adapter parsers change first.

### Validation

Internal: `python3 scripts/validate.py --strict` + `python3 scripts/audit_skills.py --ci`.
External (optional): `skills-ref validate app/skills/` from https://github.com/agentskills/agentskills.