aiaddon agent guide

AI Add-on Builder: plans, builds, checks and packages Claude skills, plugins, connectors and agents.

Structure (single branch, main): the shipped plugin is adapters/claude/ (.claude-plugin/plugin.json, adapters/claude/skills/aiaddon router and aiaddon-plan|build|maintain|review|package|prompt|clean, agents/ (aiaddon-compare, aiaddon-grade), prompts/, evals/router/cases.json and evals/evals.json for the router check and trigger simulation, plus copies of README, CHANGELOG, LICENSE, PRIVACY, SECURITY, CREDITS, PUBLIC-SAFETY, .gitignore). The root keeps .claude-plugin/marketplace.json (source ./adapters/claude), the same docs, dev/ (Python dev tools and the old hook, not shipped), evals/ (live model cases, not shipped), .github/ (CI and the release workflow). Edit the docs in both places and keep the copies identical.

Commands

• Self-test (must pass): python dev/aiaddon-review/scripts/selftest.py
• Strict validation (must pass): python dev/aiaddon-review/scripts/validate_extension.py adapters/claude --strict --target directory --require-meta author,company
• Secret scan: python dev/aiaddon-review/scripts/scan_secrets.py
• Secret and private-data scan (blocking; tree, full history, packages): python dev/aiaddon-review/scripts/scan_secrets.py . --history; false positives only in .public-safety-allow
• Router check (every eval prompt routes to its expected skill): python dev/aiaddon-review/scripts/route_check.py adapters/claude
• Version bump: dev/aiaddon-maintain/scripts/bump_version.py; package: dev/aiaddon-package/scripts/package_extension.py adapters/claude --format plugin --out <dir> (run both on adapters/claude)
• Validate: claude plugin validate adapters/claude --strict and claude plugin validate . --strict (marketplace)
• Evals (real model calls; cases live in root evals/, and claude plugin eval reads cases from inside the plugin folder, so copy adapters/claude and evals/ into one scratch folder outside the repo and run it there): claude plugin eval <scratch-copy> --trust-plugin --ablation none --scaffold --allow-tools Read Glob Grep Skill -j 4 --no-publish. Rebuild cases with python <owner-tools>/plugin-evals/regen_evals.py <plugin> <router> <fixture ids> (owner's local tools folder, not in this repo). Write results outside the repo (<owner-outputs>/<plugin>/eval-results, a local folder outside the repo); the packager includes repo files.

Workflow

1. Read the skill or script you change, plus its neighbours.
2. Make the smallest change; run the closest check, then the full gate.
3. Update CHANGELOG.md for behavior changes; log ideas in IMPROVEMENTS.md.

Rules

• Directory compliance: the shipped plugin (adapters/claude/, built into the release .plugin on a v* tag; there is no release branch) has no hooks, no scripts or other non-text files, and text-only frontmatter. Features live as recipes in adapters/claude/skills/*/references/; the Python in dev/ is maintainer tooling only. Requests that would break Anthropic rules get a plain warning and the official safe method instead.
• Never publish secrets or private data (keys, tokens, passwords, personal contact data, client names, internal URLs, local paths) in this repo or anything it builds; the secret and public-safety scans block every commit, push and release.
• Run the closest check and the full gate before committing. Never delete or weaken tests or evals. Report failed, skipped or timed-out runs honestly; NOT RUN is never a pass.
• Follow neighbouring files. Keep each SKILL.md under 500 lines; move detail into references/.
• On release, bump version in adapters/claude/.claude-plugin/plugin.json and the plugin entry in .claude-plugin/marketplace.json (skills carry no metadata block: directory policy wants text-only frontmatter); add a CHANGELOG.md entry per behavior change (root and adapters/claude/ copies). Release: push a v<version> tag; release-plugin.yml builds aiaddon.plugin.
• No commits, pushes or PRs unless asked. Work on a branch and open a PR; never push to main.
• No new dependencies without asking (scripts stay on the Python standard library).
• Never commit secrets. Never pick names or slugs without user confirmation.
• Pin any GitHub Action to a full commit SHA with the version in a comment; give each job least permissions.
• A platform fact needs its official page and the date checked. Keep private data (keys, client names, internal URLs) out of every file.
• Naming standard (validator P019 to P023): router skill name == plugin name; every other skill, agent and command is prefixed <plugin>-; action-style slugs (-review, not -reviewer). Router standard (P024 to P028): routing table, tie-breaks, default question, Skill-tool loading, router evals.
• Public safety (X008 to X013): every extension is public; .gitignore preset, PUBLIC-SAFETY.md, .env.example; never auto force-push, history rewrites need the owner's explicit OK (adapters/claude/skills/aiaddon-review/references/public-safety.md).

Model routing

Opus plans, decides, writes self-contained briefs with a report word limit, and reviews every result. Haiku for search, reading and mechanical edits. Sonnet for coding, tests and multi-step work. Do 1-2 tool calls inline.

Docs

README.md, CONTRIBUTING.md, CHANGELOG.md, SECURITY.md; ideas and feedback in IMPROVEMENTS.md.