AI Toolkit — Project Context

Mirror pair — edit both copies together. This repository keeps CLAUDE.md and AGENTS.md byte-for-byte identical. Claude Code reads CLAUDE.md; OpenCode and Pi read AGENTS.md. They are the same document under two filenames — any change to one MUST be made to the other. (Verify with diff CLAUDE.md AGENTS.md — it should print nothing.)

This is the project-level context file. It supplements, and does not replace, the global standards installed at ~/.claude/ (Claude Code), ~/.config/opencode/ (OpenCode), and ~/.pi/agent/ (Pi). Global standards — coding style, security rules, quality gates, the grounding/MCP workflow, and the Session Boot Ritual — live in those global files and are not repeated here. Related project context files: intent.md (goals, values, tradeoff hierarchy), constraints.md (musts, must-nots, escalation triggers), evals.md (test cases and CI gates).

Project Overview

• Name: AI Toolkit
• Purpose: A collection of 83 shareable skills and autonomous agents for AI-assisted software development. Supports Claude Code, OpenCode, and Pi. Edge AI, ML, robotics, and industrial-automation skills live in the companion edge-ai-robotics-automation-toolkit.
• Phase: Maintain — stable toolkit; work consists of adding new skills/agents, fixing existing ones, and keeping platform parity.
• Jira project key: N/A — task specs are tracked in conversation context or ad hoc
• Definition of success: Every skill and agent installs cleanly, follows its template (skills: the 5-section lean layout; agents: the agent section template), and works out of the box without requiring external documentation.

Technology Stack

• Content format: Markdown + YAML frontmatter — no compiled language, no build system
• Agent platforms: Claude Code (claude.ai/code), OpenCode, and Pi (pi.dev / Ollama local models)
• Global install targets: ~/.claude/ (Claude Code), ~/.config/opencode/ (OpenCode), ~/.pi/agent/ (Pi)
• Package manager: None for skills/agents; bun used in opencode/global/ for OpenCode config dependencies

Architecture

• Pattern: Flat directories by domain — skills, agents, global config, and project templates are siblings, not layers
• Two-level context stack:
  • claude/global/CLAUDE.md + opencode/global/AGENTS.md + pi/global/AGENTS.md — universal standards, installed once globally
  • CLAUDE.md (root) + AGENTS.md (root) — this repo's context only (this mirrored file)
• Key directories:
  • skills/<name>/ — skill definition (SKILL.md) + supporting docs (references/); flat, no team/professional subdirectory — Claude Code only discovers skills/<name>/SKILL.md one level deep, so the audience: frontmatter field is metadata only (it no longer selects an install subdirectory for skills; it still does for claude/agents/ and opencode/agents/, which keep their team/professional split)
  • claude/agents/ — Claude Code agent definitions, flat (.md with skills: frontmatter array)
  • opencode/agents/ — OpenCode agent definitions, flat (.md with boolean tool flags + skill() body calls)
  • claude/commands/ — Claude Code user-invoked slash commands with shell injection (flat, no audience subdir)
  • opencode/commands/ — OpenCode command equivalents with agent routing and subtask isolation (flat)
  • claude/global/ — global Claude Code files installed to ~/.claude/
  • claude/global/settings.json — hook wiring: PreToolUse credential + shell-exec-chain stops, PostToolUse bash audit log + build/lint gates
  • claude/global/hooks/ — hook script bodies (*.sh), installed to ~/.claude/hooks/; settings.json references them by path
  • claude/global/settings.local.json — permissions: bash allow/deny arrays, read allow/deny arrays
  • opencode/global/ — global OpenCode files installed to ~/.config/opencode/
  • pi/global/ — global Pi files installed to ~/.pi/agent/; SYSTEM.md is a per-project template
  • project-templates/ — context file templates users copy into their own project roots (do not edit globally)
  • tools/ — standalone runnable utilities that are not skills/agents/commands (e.g. tools/pdf2md/, tools/web2md/, tools/code2md/, tools/ollama-evals/); excluded from primitive counts and parity checks

• Platform primitive support — harness and model provider are orthogonal (all three run local or cloud models); what differs is which primitives each harness natively supports:

  Primitive	Claude Code	OpenCode	Pi
  Skills	yes	yes	yes — same skills/ tree, /skill:<name> to invoke
  Commands	claude/commands/	opencode/commands/	prompt templates (~/.pi/agent/prompts/*.md) — args only, no ! shell injection
  Agents / subagents	yes	yes	no — Pi extensions cannot spawn child agents
  Hooks	shell, settings.json	yes	TypeScript extension events (tool_call can block, tool_result can rewrite)
  MCP	native	native	via an extension; grounded-code-mcp also ships a CLI Pi calls directly

  Pi is a first-class target for skills and commands, and deliberately not for agents — the boundary is Pi's capability surface plus the local model tier, not neglect. Multi-phase work still runs on Pi: QRSPI/QRASPI phases are artifact-gated (each phase reads a markdown artifact and writes the next), so the human drives phase-to-phase where the agents would.

• Non-obvious constraints: claude/global/, opencode/global/, and pi/global/ files affect every project on the user's machine — changes require explicit human approval before committing

Quick Reference

• Skills: skills/<n>/SKILL.md — flat, no subdir; audience: frontmatter (team | professional) is metadata only. 5-section lean layout (depth → references/), gold standard: skills/cargo-package-scaffold/SKILL.md
• Agents: claude/agents/<n>.md (Claude Code) | opencode/agents/<n>.md (OpenCode) — flat, must stay in parity
• Commands: claude/commands/<n>.md (Claude Code) | opencode/commands/<n>.md (OpenCode) — flat, no audience subdir
• Global files: claude/global/ → installs to ~/.claude/ | opencode/global/ → installs to ~/.config/opencode/ | pi/global/ → installs to ~/.pi/agent/
• Hooks: claude/global/settings.json (wiring) + claude/global/hooks/*.sh (bodies) — credential + shell-exec-chain stops (PreToolUse), bash audit log + post-write build/lint gates (PostToolUse)
• Permissions: claude/global/settings.local.json — bash allow/deny arrays, read allow/deny arrays
• Project templates: project-templates/ — copy into target project roots, do not edit globally

Key Files

Skill Conventions

Each skill lives in skills/<name>/ with a SKILL.md and a references/ directory — flat, no team/professional subdirectory. Claude Code only discovers skills/<name>/SKILL.md one level deep, so nesting by audience breaks discovery. claude/agents/ and opencode/agents/ are flat too (see the 2026-08-08 Persistent Decision). The audience: frontmatter field (team | professional) is retained as pure metadata — it groups a skill (and its paired agent, if any) into the README's Team/Professional sections but no longer selects an install path anywhere — and is backfilled by scripts/add_frontmatter.py, which now walks skills/*/.

SKILL.md Frontmatter

---
name: skill-name
audience: team  # team | professional — metadata; selects the install subdir for this skill's paired agent (if any), not for the skill itself
description: >
  What the skill does. Trigger phrases like "keyword1", "keyword2".
disable-model-invocation: true  # optional: prevents auto-invocation; use for interactive or conversational skills
---

Skill Tiers

Minimal-tier skills have no prescribed section structure — just focused instructions. Full-template skills follow the 5-section lean layout below. Every always-loaded section is a per-invocation token tax, so depth — principle tables, anti-patterns, discipline rules, recovery steps, and code/report templates — lives in references/ and loads just-in-time, not in SKILL.md.

Description Format

The description field is the only thing the model sees when deciding which skill to load. Quality here determines trigger reliability.

• Max 1024 chars
• Third person: "Scaffolds...", "Audits...", "Extracts..." — not "I will..." or "You can..."
• First sentence: what the skill does
• Second sentence: "Use when [specific trigger scenarios]"
• Include "Do NOT use when..." for negative triggers

Good:

description: >
  Scaffolds NuGet package metadata, CI/CD pipeline, and test harness.
  Use when publishing a new library to NuGet.org. Do NOT use for
  internal workspace-only libraries; use dotnet-vertical-slice instead.

Bad (too vague — triggers on everything):

description: >
  A comprehensive and powerful tool for NuGet package management.
  Very useful for .NET developers.

5-Section Lean Layout (in order)

A full-template SKILL.md carries only what the model needs to act. Everything else is depth that loads on demand from references/.

1. Title + Epigraph -- # Skill Name with 1 relevant quote
2. Core Philosophy -- design rationale + a numbered Non-Negotiable Constraints list. The Critical/High principles live here as constraints; the full principle table goes to references/.
3. Workflow -- phased lifecycle (e.g., DETECT, SCAN, REPORT, RECOMMEND) in one compact block, with exit criteria. Decision trees and long step prose go to references/.
4. State Block -- unique XML tag (e.g., <tdd-state>, <arch-review-state>) for multi-turn tracking
5. Output Template -- pointers to the report/code templates in references/, not the templates inline
6. Integration with Other Skills -- a table cross-referencing related skills

Pushed to references/ (depth, loaded just-in-time): the full Domain Principles table, Anti-Patterns table, AI Discipline (WRONG/RIGHT) rules, Error Recovery scenarios, and all code/report templates. These remain authoritative — they are relocated, not deleted, and every reference file is named by a pointer in SKILL.md so nothing becomes undiscoverable.

Gold-standard lean examples: skills/qraspi-skeleton/SKILL.md (phase driver) and skills/cargo-package-scaffold/SKILL.md (domain scaffolder with references/ depth).

References Directory

Each references/ directory contains 2-5 supporting files: code examples, decision matrices, checklists, configuration templates.

When Adding a Skill

Choose a tier first (see the Skill Tiers table above). Set audience: in the frontmatter (team | professional) — pure metadata, grouping the skill (and its paired agent, if any) into the README's Team/Professional sections. scripts/add_frontmatter.py backfills it when missing.

Minimal-tier steps:

1. Create skills/<new-name>/SKILL.md with focused instructions (no template to copy)
2. Add disable-model-invocation: true for interactive or conversational skills
3. Create skills/<new-name>/references/ with ≥ 1 supporting file — skip it if the SKILL.md is under 20 lines and has no depth to split out
4. Skip the agent/command/registration steps below unless the skill is user-invocable

Full-template steps:

1. Copy the gold standard: cp -r skills/cargo-package-scaffold skills/<new-name>
2. 5-section lean layout — keep Core Philosophy / Workflow / State / Output Template / Integration in SKILL.md; push depth to references/; ≥ 2 reference files
3. Add agent entries in both claude/agents/ and opencode/agents/
4. Add command entries in both claude/commands/ and opencode/commands/ if user-invocable
5. Update counts and tables: README.md badge + at-a-glance + structure comments; this file's Purpose line + Open Loops + Skill Suites table
6. Add a Green / Yellow / Red entry for the new skill in pi/SKILLS-local.md

Agent Conventions

Agents exist in two flavors with identical behavior but different formats:

Claude Code (claude/agents/<name>.md)

---
name: agent-name
description: What the agent does
tools: Read, Edit, Write, Bash, Glob, Grep
model: inherit
skills:
  - skill-name-1
  - skill-name-2
---

OpenCode (opencode/agents/<name>.md)

---
description: What the agent does
mode: subagent
tools:
  read: true
  edit: true
  write: true
  bash: true
  glob: true
  grep: true
---

Key difference: Claude uses skills: array in frontmatter; OpenCode uses skill({ name: "..." }) calls in the body.

10 Mandatory Agent Sections (in order)

1. Title + Epigraph
2. Core Philosophy
3. Guardrails
4. Autonomous Protocol
5. Self-Check Loops
6. Error Recovery
7. AI Discipline Rules
8. Session Template
9. State Block (unique XML tag per agent, e.g., <tdd-state>, <code-review-state>)
10. Completion Criteria

Command Conventions

Commands are user-invoked (typed as /command-name). Use ! shell injection to give the agent live state before it acts. Skills are model-invoked — different primitive, different directory.

Claude Code format:

---
description: What it does. Trigger phrase for slash-command discovery.
allowed-tools: Bash(dotnet test:*), Read, Edit
---

<live_state>
!`command that captures current state`
</live_state>

Instruction using the injected state above.

OpenCode additions — agent:, subtask:, optional model::

---
description: What it does.
agent: build
subtask: true
---

Use subtask: true for read-heavy commands (review, research, context-prime). Use subtask: false for commands that write files (new-feature, migrate) — they need primary context.

Hook Enforcement (settings.json)

claude/global/settings.json installs deterministic hooks that run outside the LLM:

Hook bodies live in claude/global/hooks/*.sh and install to ~/.claude/hooks/; settings.json only references them by path. Three rules govern whether a hook works at all — each has silently disabled these hooks before:

• matcher matches the tool NAME only, as a literal or unanchored regex. Permission-rule syntax (Bash(*), Write(*.cs)) does not work here and matches nothing. Filter by file extension inside the script, not in the matcher.
• Tool input arrives as JSON on stdin — read it with jq (.tool_input.command, .tool_input.file_path). There are no CLAUDE_TOOL_INPUT_* environment variables; referencing them yields an empty string and the hook fails open, silently allowing what it should block.
• Exit 2 blocks only on PreToolUse. PostToolUse runs after the tool call and cannot block — its output is advisory. Messages must go to stderr to be surfaced.

A misconfigured hook produces no error — it simply never runs. Verify with the checks in claude/global/README.md rather than assuming.

These run regardless of model instruction and cannot be bypassed by prompt injection. Permissions (interactive allow/deny) live separately in claude/global/settings.local.json — hooks for deterministic enforcement, permissions for interactive approval; keep them in separate files.

Contributor Validation

No compiled artifacts. Validation is structural.

# Count skills
find skills -name "SKILL.md" | wc -l

# Verify a full-template skill has the 5 lean sections (in-fence template headers may push this higher)
grep -c "^## " skills/<n>/SKILL.md

# Check agent parity (counts must match) — agents live under team/ and professional/ subdirs
find claude/agents -name "*.md" | wc -l
find opencode/agents -name "*.md" | wc -l

# Check command parity (counts must match) — commands are flat
ls claude/commands/*.md | wc -l
ls opencode/commands/*.md | wc -l

# Confirm this mirror pair is in sync (should print nothing)
diff CLAUDE.md AGENTS.md

Editing Guidelines

• Follow the 5-section lean layout when creating or modifying skills; push depth to references/.
• Keep both claude/agents/ and opencode/agents/ versions in sync.
• Every full-template skill must have a references/ directory with at least 2 supporting files (minimal-tier: ≥ 1, or none if the SKILL.md is under 20 lines).
• State block XML tags must be unique across all skills and agents.
• Frontmatter description fields must include trigger phrases for slash-command discovery.
• In Python code examples, avoid PyTorch evaluation mode calls that trigger security hooks. Use model.train(False) instead.
• Keep CLAUDE.md and AGENTS.md byte-identical — any edit to one must be made to the other; confirm with diff CLAUDE.md AGENTS.md.

Global File Caution

Files in claude/global/, opencode/global/, and pi/global/ affect every project on the user's machine after install. Changes to any global file require explicit review before committing. Do not batch-edit them alongside skill or agent changes.

These files are public templates. Never embed specific book titles, personal document names, personal file paths, or user-specific tool references in them. Collection descriptions must describe topic domains only (e.g., "Rust language: ownership, async, Tokio"), not the specific documents a particular user has ingested. Personal enrichment belongs in the installed copies (~/.claude/CLAUDE.md, ~/.config/opencode/AGENTS.md, ~/.pi/agent/AGENTS.md), not the repo source.

Persistent Decisions

Open Loops

• Skill count (currently 83) — update this file and README when skills are added or removed. jira-review removed 2026-09-05 (was 84 → 83, team 73 → 72) — see the paired Persistent Decision entry. Vendored/adjacent skill removal 2026-08-08 (was 94 → 84, team 83 → 73, professional 12 → 11): grilling, grill-me, grill-with-docs, codebase-design, domain-model, improve-codebase-architecture (mattpocock vendor, sunset — see the 2026-08-08 Persistent Decision), para-file, para-review, substack-writer — commit a2e1643/6904917. zoom-out removed 2026-07-22 (was 95 → 94, team 83 → 82) — deleted upstream, local fork orphaned. Grill family re-vendored 2026-07-22 (was 93 → 95, team 81 → 83): grilling + grill-with-docs added alongside the re-vendored grill-me; /grill-with-docs added in both runtimes (commands 25 → 26). Vue family added 2026-07-19 (was 87 → 93, team 75 → 81): 6 skills (vue-architecture-checklist, vue-security-review, vue-feature-slice, vue-component-scaffolder, vue-app-scaffolder, vue-modernization-analyzer), mirroring the React family exactly; no commands (React has none either). Product & GitHub suite retired 2026-07-11 (was 90 → 87, team 78 → 75): dropped to-prd + to-issues (mattpocock PRD writer + PRD→GitHub-issues decomposer), then triage-issue (GitHub/Jira bug triage) — all as out-of-scope for the engineering-workflow toolkit: specs live in Jira/Confluence and the QRSPI/QRASPI workflows own technical spec/plan. All three skill-only, no agents/commands. to-prd/to-issues attribution entries removed from .matt-pocock-attribution.yml; the Product & GitHub suite row removed from the Skill Suites table. codebase-design added 2026-07-11 (was 89 → 90): the mattpocock deep-module vocabulary skill (team, team 77 → 78) — glossary of module/interface/depth/seam/adapter/leverage/locality + references/DEEPENING.md + references/DESIGN-IT-TWICE.md; disable-model-invocation vocabulary provider, no agent/command. Fills the APOSD vocabulary dependency the earlier improve-codebase-architecture port assumed but never imported; cross-linked from that skill's intro + Integration. substack-writer added 2026-07-04 (was 88 → 89): multi-pass editorial pipeline turning raw technical notes into publication-quality Substack/blog posts (professional); skill-only, no agent/command (professional 11 → 12, team unchanged at 77). oss-vetting added 2026-06-25 (was 87 → 88): federal OSS/SBOM vetting assessment skill (team), with paired oss-vetting-agent in both runtimes (agents 44/44 → 45/45) and /oss-vetting command in both runtimes (commands 24/24 → 25/25). PARA knowledge-management pair added 2026-06-20 (was 85 → 87): para-file + para-review (team), each with /para-file + /para-review commands in both runtimes (commands 22 → 24); no agents. Edge supplement spin-out 2026-06-20 moved 5 more out (was 90 → 85): model-optimization, ollama-model-workflow, rag-pipeline-python, rag-pipeline-dotnet, mcp-server-scaffold → edge-ai-robotics-automation-toolkit. Quality prune 2026-06-20 dropped 8 (was 98 → 90): the edge/IoT/robotics cluster (picar-x-behavior, jetson-deploy, sensor-integration, edge-cv-pipeline, fleet-management, anomaly-detection) + caveman + tdd-pair. dotnet-controller-api-scaffolder added 2026-06-03 (was 102 → 103): controller-based Web API scaffolder that conforms to existing conventions; skill-only, no agent/command (matches the .NET family convention — minimal-api-scaffolder et al. have no agents). Same change made dotnet-architecture-checklist style-aware (layered/N-tier controller branch via references/layered-ntier.md) — no count change. QRSPI added 5 phase skills 2026-06-02 (was 81); QRASPI added 8 (fitness-functions + the 7 phase/graduate skills) 2026-06-03 (was 86, → 94); TDD cluster consolidated 8→5 on 2026-06-03 (→ 91); cross-language architecture+security parity 2026-06-03 (renamed python-arch-review→python-architecture-checklist; +php-architecture-checklist, +php-security-review, +security-review-federal; −dotnet-security-review-federal, −python-security-review-federal → 92); PHP family parity 2026-06-03 (+php-feature-slice, +php-api-scaffolder, +php-package-scaffold, +php-migration-manager → 96); React family parity 2026-06-03 (+react-architecture-checklist, +react-security-review, +react-feature-slice, +react-component-scaffolder, +react-app-scaffolder, +react-modernization-analyzer → 102 → 103 with dotnet-controller-api-scaffolder); RPI sunset 2026-06-19 removed the 4 rpi-* skills + spec-implement (→ 98).
• Agent count parity — Claude Code (51) vs. OpenCode (51) — Vue family added vue-arch-checklist-agent, vue-security-agent, vue-modernization-agent, vue-feature-slice-agent, vue-component-scaffold-agent, vue-app-scaffold-agent in both runtimes 2026-07-19 (was 45/45 → 51/51); oss-vetting-agent added in both runtimes 2026-06-25 (was 44/44 → 45/45); edge supplement spin-out 2026-06-20 moved model-optimization-agent to edge-ai-robotics-automation-toolkit in both runtimes (was 45/45 → 44/44); quality prune 2026-06-20 removed sensor-anomaly-agent + fleet-deployment-agent in both runtimes (was 47/47 → 45/45); QRSPI added qrspi-orchestrator + qrspi-implement 2026-06-02 (was 35/35, resolved 2026-05-19); QRASPI added qraspi-orchestrator + qraspi-builder 2026-06-03 (was 37/37); PHP family parity 2026-06-03 added php-feature-slice-agent, php-api-scaffold-agent, php-package-agent, php-migration-agent in both runtimes (was 39/39, → 43/43); React family parity 2026-06-03 added react-feature-slice-agent, react-component-scaffold-agent, react-app-scaffold-agent, react-security-agent, react-modernization-agent, react-arch-checklist-agent in both runtimes (was 43/43, → 49/49); RPI sunset 2026-06-19 removed rpi-planner/rpi-implement in both runtimes (→ 47/47).
• Commands layer — claude/commands/ (22 commands) and opencode/commands/ (22 commands) — /grill-me, /grill-with-docs, /para-file, /para-review deleted 2026-08-08 (orphaned by the same-day skill cleanup; was 26/26 → 22/22). /grill-with-docs added in both runtimes 2026-07-22 (was 25/25 → 26/26) — /oss-vetting added in both runtimes 2026-06-25 (was 24/24 → 25/25) — PARA pair added /para-file + /para-review 2026-06-20 (was 22/22) — QRSPI added 5 (/qrspi-questions…/qrspi-implement) 2026-06-02 (was 10/10); QRASPI added 7 (/qraspi-questions…/qraspi-graduate) 2026-06-03 (was 15/15). No rpi-* commands, so sunset leaves commands at 22.
• Lean-layout migration (line count) — every full-template SKILL.md is ≤ 200 lines (completed 2026-06-26). Re-verify with the Contributor Validation commands after adding or editing a skill.
• Lean-layout migration (section canonicalization) — 125 non-canonical ## sections remain, affecting 38 full-template skills, per skill-evals lint --rule SK023 (amended 2026-08-02; see that Persistent Decision). Top offenders: AI Discipline Rules (28), Error Recovery (15), Knowledge Base Lookups (12), Domain Principles (8), Anti-Patterns (8).

Skill Suites

Team

Project Boot Ritual

Follow the global Session Boot Ritual (see global CLAUDE.md / AGENTS.md). Repo-specific deltas: read this file plus intent.md and constraints.md, and confirm the Persistent Decisions and Open Loops above before starting. Tooling (grounded-code-mcp, Microsoft Learn MCP, grounding workflow) is defined globally — not repeated here.