docs(sdk-ai-tools): Add Warden page, AGENTS.md template, and expand skills docs

develop-docs/sdk/getting-started/ai-tools/index.mdx

@@ -1,7 +1,19 @@
 ---
 title: AI Tools
-description: Explore recommended AI tools and agentic skills for SDK development. Learn which automations and workflows to use, and when, to boost quality, consistency, and productivity across all Sentry SDKs.
+description: AI tools available for SDK development at Sentry — how they layer together and when to use each.
 sidebar_order: 6
 ---
 
+This section covers the AI tools available to SDK engineers, how they layer together, and when to reach for each.
+
 <PageGrid />
+
+## When to Use Each Tool
+
+| Tool | What It Is | Scope | When to Use | Expectation |
+|---|---|---|---|---|
+| **[AGENTS.md](/sdk/getting-started/templates/agents-md-template/)** | Always-loaded repo instructions | Whole repo | Every SDK repo | <StatusBadge type="required" /> |
+| **[Skills](/sdk/getting-started/ai-tools/skills/)** | Portable AI playbooks | Cross-repo | Repeated workflows | <StatusBadge type="recommended" /> |
+| **[dotagents](/sdk/getting-started/ai-tools/skills/#dotagents)** | Skills package manager | Team/repo | Sharing skills | <StatusBadge type="recommended" /> |
+| **[Warden](/sdk/getting-started/ai-tools/warden/)** | AI-powered code review | Per PR/CI | Enforcing standards | <StatusBadge type="encouraged" /> |
+| Rules files | Workflow-specific instructions | Per task | Fixed conventions | <StatusBadge type="recommended" /> |

develop-docs/sdk/getting-started/ai-tools/skills/index.mdx

@@ -4,38 +4,86 @@ description: Learn which skills to use, and when, to boost quality, consistency,
 sidebar_order: 2
 ---
 
-## Skills Package Manager (dotagents)
+Agent skills teach AI coding agents how to perform specific workflows. Encode a workflow once in a skill and the agent loads it on demand. Skills live in a `skills/` directory inside your agent's config folder (e.g., `.claude/skills/`, `.cursor/skills/`) and follow the [Agent Skills open format](https://agentskills.io/specification).
 
-A package manager for .agents directories that enables you to declare agent skill dependencies in `agents.toml`, lock versions for reproducibility, and allow every tool on your team to reliably discover skills from a unified location.
+## Using Skills Safely
 
-https://github.com/getsentry/dotagents
+<Alert level="warning" title="Skills are a potential attack vector">
 
+Skills can inject packages or hide malicious instructions in HTML comments. Only install skills from [`getsentry/skills`](https://github.com/getsentry/skills), [`getsentry/sdk-skills`](https://github.com/getsentry/sdk-skills), or your own repo. Do not use auto-discovery from [skills.sh](https://skills.sh/) or similar.
 
-## Skills
+</Alert>
 
-### Sentry Skills
+## dotagents
 
-Agent skills for Sentry employees, following the Agent Skills open format.
+[dotagents](https://github.com/getsentry/dotagents) is a package manager for `.agents` directories. Declare skill dependencies in `agents.toml`, lock exact versions in `agents.lock`, and dotagents symlinks them into wherever your coding agent looks.
 
-https://github.com/getsentry/skills/
+Use [dotagents.sentry.dev](https://dotagents.sentry.dev/) as the Sentry distribution hub — it's wired up to `getsentry/skills` and keeps everything in sync. The main `sentry` repository already has dotagents configured; use it to vend skills into SDK repos or manage personal-scope skills.
 
+### Quick Setup
 
-### Sentry SDK Skills
+```bash
+# Initialize dotagents (creates agents.toml)
+npx @sentry/dotagents init
 
-Agent skills for managing feature development across Sentry SDKs, following the Agent Skills open format.
+# Add skills from the trusted getsentry/skills repo
+npx @sentry/dotagents add getsentry/skills --name find-bugs
+npx @sentry/dotagents add getsentry/skills --name code-review
 
-https://github.com/getsentry/sdk-skills/
+# Or add all skills from a repo
+npx @sentry/dotagents add getsentry/skills
 
+# Install / sync all declared skills
+npx @sentry/dotagents install
+```
 
-### Sentry Reproduction Skill (repro)
+Commit `agents.toml` and `agents.lock` so every engineer on the team gets the same skills automatically.
 
-This skill enables agents and developers to quickly generate, store, and share minimal reproduction environments for issues affecting Sentry SDKs and integrations. It automates the creation of reproducible test cases in isolated sandboxes, streamlining bug reporting, verification, and collaborative debugging across the Sentry ecosystem. This skill improves issue turnaround and makes it easier to validate fixes or demonstrate regressions in a consistent environment.
+| Command | Description |
+|---|---|
+| `init` | Create `agents.toml` and `.agents/skills/` |
+| `add <source>` | Add a skill dependency |
+| `remove <name>` | Remove a skill |
+| `install` | Install all skills from `agents.toml` |
+| `update [name]` | Update skills to latest versions |
+| `list` | Show installed skills and their status |
+| `sync` | Reconcile symlinks and verify state |
 
-https://github.com/getsentry/repro
+## Available Skills
+
+### Sentry Skills
+
+Agent skills for Sentry employees, covering general workflows like committing, opening PRs, code review, finding bugs, and security review.
+
+https://github.com/getsentry/skills
+
+### Sentry SDK Skills
+
+Agent skills for managing feature development across Sentry SDKs — cross-SDK rollouts, Linear project setup, daily standups, and more.
 
+https://github.com/getsentry/sdk-skills
+
+### Sentry Reproduction Skill
+
+Generates minimal reproduction environments for SDK issues — reproducible test cases in isolated sandboxes for bug reporting, verification, and collaborative debugging.
+
+https://github.com/getsentry/repro
 
 ### Obra's Superpowers
 
-An agentic skills framework that provides structured software development workflows for AI coding agents. It includes composable skills that automatically trigger at appropriate moments — covering brainstorming, implementation planning, test-driven development, subagent-driven parallel execution, code review, and systematic debugging. Rather than letting agents jump straight into writing code, Superpowers enforces disciplined processes that improve quality and maintain alignment with approved designs.
+Structured software development workflows for AI agents: brainstorming, implementation planning, TDD, parallel execution, code review, and systematic debugging.
 
 https://github.com/obra/superpowers
+
+## Contributing a Skill
+
+If you find yourself explaining the same workflow to an agent repeatedly, formalize it as a skill. Skills follow the [Agent Skills specification](https://agentskills.io/specification):
+
+```text
+skill-name/
+  SKILL.md        # YAML frontmatter (name, description) + markdown instructions
+```
+
+Add new skills to [`getsentry/skills`](https://github.com/getsentry/skills) (for general Sentry workflows) or [`getsentry/sdk-skills`](https://github.com/getsentry/sdk-skills) (for SDK-specific workflows) rather than a personal repo, so the whole team benefits.
+
+For guidance on writing effective skills, see [Skill Synthesis](https://cra.mr/skill-synthesis) — using your own codebase's history, past failures, and real patterns as source material produces significantly better results than generic guidance.

develop-docs/sdk/getting-started/ai-tools/warden/index.mdx

@@ -0,0 +1,29 @@
+---
+title: Warden
+description: AI-powered code review tool that runs configurable skills against code changes, locally or in CI.
+sidebar_order: 4
+---
+
+[Warden](https://warden.sentry.dev/) runs AI-powered skills against code changes — locally before you push, or automatically on pull requests in CI.
+
+## How It Works
+
+On every run, Warden:
+
+1. **Detects changes** — identifies modified files, hunks, or directories
+2. **Matches triggers** — compares changes against each skill's activation rules
+3. **Executes skills** — runs the matching AI prompts (via Claude) on the relevant code
+4. **Reports findings** — delivers results with severity, location, and optional fix suggestions
+
+## Why Use It for SDK Development
+
+SDK repos have consistency requirements that are hard to enforce through code review alone. Warden helps by:
+
+- **Running checks consistently** — SDK-specific conventions, security, and API design run on every PR, not only when a reviewer notices something.
+- **Catching issues before human review** — findings surface early, so review time is spent on logic and design.
+- **Using Claude's reasoning, not syntax rules** — detects nuanced issues (broken API contracts, spec violations) that linters can't express.
+- **Turning findings into permanent rules** — the `warden-lint-judge` Claude Code skill can propose lint rules from findings so the same issue can never recur.
+
+## Setup
+
+See the [Warden guide](https://warden.sentry.dev/guide) for installation, local usage, and CI integration via the Warden GitHub Action.

develop-docs/sdk/getting-started/templates/agents-md-template.mdx

@@ -1,10 +1,69 @@
 ---
 title: AGENTS.md
 sidebar_order: 10
+description: Boilerplate AGENTS.md template for Sentry SDK repositories. Teaches AI coding agents about your project's commands, conventions, and standards.
 ---
 
-<CopyableCard title="AGENTS.md">
+`AGENTS.md` is a Markdown file at the root of your repository that AI coding agents load automatically at the start of every session. Claude Code reads `CLAUDE.md` — symlink it to `AGENTS.md` so there's one source of truth.
 
-TBD
+## What Belongs in AGENTS.md
 
-</CopyableCard>
+Keep it focused on what the agent **cannot easily discover by reading the code**. Generic instructions ("follow existing patterns", "write clean code") add noise without helping. What agents consistently get wrong without explicit guidance:
+
+- **Commands** — exact invocations for test, lint, format, and build. Especially non-obvious ones like tox environments, specific flags, or required env setup.
+- **Non-obvious conventions** — things that look wrong but are intentional, or constraints that aren't visible in the code (e.g. "all migrations must be backward-compatible, we run blue-green deploys").
+- **Changelog and commit format** — agents will guess the wrong format without explicit instruction.
+- **Links to specs and standards** — the SDK spec, platform docs, and cross-SDK alignment references the agent can't find on its own.
+
+**Keep it short.** Every line costs reasoning tokens. Prefer automated enforcement (linters, type checkers, CI) over written rules — tooling catches mistakes reliably; instructions don't always.
+
+**Write instructions positively.** "Always update `CHANGELOG.md` under `## Unreleased`" works better than "don't forget the changelog." Agents struggle with negations.
+
+**Iterate from observed failures.** Add an instruction when you see the agent make a specific mistake, not preemptively. Over time this produces a lean file of rules that actually matter for your repo.
+
+Task-specific workflows (PR format, commit style, changelog) belong in rules files — see [AI Agent Skills](/sdk/getting-started/ai-tools/skills/) for how to set them up alongside skills.
+
+## Good Examples in SDK Repositories
+
+Check if the repository already has one before starting from scratch. The following repos have well-structured examples worth referencing:
+
+- [`getsentry/sentry-cocoa`](https://github.com/getsentry/sentry-cocoa/blob/master/AGENTS.md) — written explicitly for LLM agents: tables over prose, nested `AGENTS.md` per subdirectory for scoped context
+- [`getsentry/sentry-javascript`](https://github.com/getsentry/sentry-javascript/blob/master/AGENTS.md) — monorepo setup, clear commands table, package manager conventions
+- [`getsentry/sentry-dotnet`](https://github.com/getsentry/sentry-dotnet/blob/master/AGENTS.md) — build system detail, solution filter table showing which filter to use when
+- [`getsentry/sentry-react-native`](https://github.com/getsentry/sentry-react-native/blob/master/AGENTS.md) — agent responsibilities section, quick reference command table
+- [`getsentry/sentry-cli`](https://github.com/getsentry/sentry-cli/blob/master/AGENTS.md) — clear language/architecture overview for a multi-language project
+- [`getsentry/sentry-python`](https://github.com/getsentry/sentry-python/blob/master/AGENTS.md) — focused tox workflow: how to test, lint, and type-check correctly
+
+## Template
+
+Remove sections that don't apply and replace all `[placeholder]` values with real content.
+
+```markdown
+# Agent Instructions
+
+[SDK name] SDK for Sentry — error monitoring and performance tracing for [language/platform].
+
+## Commands
+
+| Task | Command |
+|------|---------|
+| Install | `[install command]` |
+| Test (all) | `[test command]` |
+| Test (single) | `[single test command]` |
+| Lint | `[lint command]` |
+| Format | `[format command]` |
+| Build | `[build command]` |
+| Type check | `[type check command]` |
+
+## Conventions
+
+- Always update `CHANGELOG.md` for user-facing changes — add an entry under `## Unreleased`
+- Commit format: `type(scope): description` — e.g. `fix(transport): handle connection timeout`
+- [Any non-obvious constraint specific to this repo]
+
+## References
+
+- SDK spec: https://develop.sentry.dev/sdk/
+- Platform docs: https://docs.sentry.io/platforms/[platform]/
+- Cross-SDK standards: https://develop.sentry.dev/sdk/getting-started/
+```

src/components/statusBadge/index.tsx

@@ -1,4 +1,4 @@
-type StatusType = 'yes' | 'no';
+type StatusType = 'yes' | 'no' | 'required' | 'recommended' | 'encouraged';
 
 interface StatusBadgeProps {
   type: StatusType;
@@ -13,6 +13,18 @@ const STATUS_BADGE_CONFIG: Record<StatusType, {className: string; label: string}
     label: 'No',
     className: 'bg-red-100 text-red-800 dark:bg-red-900 dark:text-red-200',
   },
+  required: {
+    label: 'Required',
+    className: 'bg-orange-100 text-orange-800 dark:bg-orange-900 dark:text-orange-200',
+  },
+  recommended: {
+    label: 'Recommended',
+    className: 'bg-blue-100 text-blue-800 dark:bg-blue-900 dark:text-blue-200',
+  },
+  encouraged: {
+    label: 'Encouraged',
+    className: 'bg-purple-100 text-purple-800 dark:bg-purple-900 dark:text-purple-200',
+  },
 };
 
 export function StatusBadge({type}: StatusBadgeProps) {