docs: add guide and skill for adding new agent support

[nycjay]

• docs/development/adding-agents.md: comprehensive reference covering levels of support, step-by-step instructions, hook format reference, and common pitfalls
• .claude/skills/add-agent/SKILL.md: interactive skill that walks through the agent addition workflow with verification checkpoints; includes a self-update section so the skill stays current
• .kiro/skills/add-agent -> symlink to .claude/skills/add-agent so the skill works for both Claude Code and Kiro CLI users

Description

Adds documentation and a Kiro skill to make adding new agent support easier for contributors.

• docs/development/adding-agents.md: Comprehensive reference guide covering levels of support (basic, hooks, sandbox), step-by-step instructions with code examples, hook format reference for each agent type, and common pitfalls.
• .kiro/skills/add-agent/SKILL.md: Interactive skill that walks through the agent addition workflow with verification checkpoints at each step. Includes a self-update section so the skill stays current as the process evolves.

Motivated by the experience of adding Kiro CLI support (#958), where the process required significant discovery across multiple files with no centralized guide.

PR Type

• New Feature
• Bug Fix
• Refactor
• Documentation
• Infrastructure / CI

Checklist

• I understand the code I am submitting
• New and existing tests pass
• Documentation was updated where necessary
• For UI changes: included screenshot or recording

AI Usage

• No AI was used
• AI was used for drafting/refactoring
• This is fully AI-generated

AI Model/Tool used:
Claude Sonnet 4 via Kiro CLI

Any Additional AI Details you'd like to share:
Written based on the actual experience of implementing Kiro CLI agent support in #958.

NOTE:
When responding to reviewer questions, please respond yourself rather than copy/pasting reviewer comments into an AI and pasting back its answer. We want to discuss with you, not your AI :)

• I am an AI Agent filling out this form (check box if true)

[njbrake]

Note: this comment was drafted by Claude via back-and-forth with @njbrake. The reasoning and decisions are his; the prose is Claude's.

Thanks @nycjay! The doc is great, and folding the #958 review lessons into a follow-up commit was a nice touch. I'd like to land the doc with a few small fixups, but hold off on the skill files for this PR. Details below.

Doc: ready to merge after these fixes

docs/development/adding-agents.md is exactly what #963 was asking for. Three small fixes before merge:

1. Hardcoded kiro in a generic command (line 209): cargo test --lib -- agents kiro container_config status_hook_env_prefix. Surrounding text uses <youragent> as the placeholder; this line should too.

2. Website sync. docs/ is the canonical source for the public site. Per AGENTS.md, new pages need entries in website/scripts/sync-docs.mjs (PAGES and URL_MAP) and website/src/data/docsNav.ts. Happy to take that on if it's easier; otherwise it's a small addition.

3. Cross-link from AGENTS.md. A one-line pointer under "Project Structure & Module Organization" so contributors find this from the canonical project doc.

Skill: holding off for this PR

I'd like to punt on .claude/skills/add-agent/SKILL.md and the .kiro/skills/add-agent symlink, and ship just the doc. Two reasons, neither about quality:

1. It's a precedent decision. This is the first PR to add .claude/ and .kiro/ directories at the repo root, and committing to ship skills with the repo is a call I want to make deliberately rather than inherit from a single PR. Lots of repos do it; I just want to think it through on its own merits.

2. It largely duplicates the doc. The skill is essentially the same content with checkpoints, which means when one drifts the other has to follow. The skill's own "Keeping This Skill Updated" section is honest about that drift risk, which is a tell that the duplication is structural.

Could you drop those two files from this PR and we'll land just the doc? Skill content isn't lost; it's preserved in the PR history if I decide later that AoE wants committed skills.

Thanks again for both this PR and #958, and especially for the pitfalls section that bakes review lessons back into the docs. That's exactly the right pattern.

[nycjay]

Makes perfect sense - I'll make those changes shortly. On our internal repos, we've been adding more agent skills for content like this, but I get that it's a change in precendent.