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

## Describe your PR

Builds out the AI tools section for SDK developers — previously most
pages were stubs or sparse lists — and establishes normative
requirements for AI tooling in the standards.
- templates/agents-md-template.mdx — Was a TBD placeholder. Now a full
page: what belongs in AGENTS.md, writing tips, real SDK examples, a
reference to the sentry-skills:agents-md skill, and a copy-ready
  template
- ai-tools/skills/index.mdx — Expanded from a sparse list of links into
a full page: dotagents quick-setup guide, security warning, command
reference, contributing guidance
- ai-tools/code-review/index.mdx — Added Warden section: how it works,
why it matters for SDK development, setup pointer
- ai-tools/index.mdx — Turned into a real landing page with an
orientation table and a pointer to standards for requirement levels
- standards/repository-docs.mdx (v1.1.0) — New AI Skills SpecSection:
SDK repos SHOULD have dotagents configured and use rules files for fixed
conventions
- standards/review-ci.mdx (v1.1.0) — New Warden SpecSection: SDK repos
SHOULD have Warden in CI


## IS YOUR CHANGE URGENT?

Help us prioritize incoming PRs by letting us know when the change needs
to go live.
- [ ] Urgent deadline (GA date, etc.):
- [ ] Other deadline:
- [x] None: Not urgent, can wait up to 1 week+

## SLA

- Teamwork makes the dream work, so please add a reviewer to your PRs.
- Please give the docs team up to 1 week to review your PR unless you've
added an urgent due date to it.
Thanks in advance for your help!

## PRE-MERGE CHECKLIST

*Make sure you've checked the following before merging your changes:*

- [ ] Checked Vercel preview for correctness, including links
- [ ] PR was reviewed and approved by any necessary SMEs (subject matter
experts)
- [ ] PR was reviewed and approved by a member of the [Sentry docs
team](https://github.com/orgs/getsentry/teams/docs)

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Stephanie Anderson <stephanie.anderson@sentry.io>

Author: 3 people

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

@@ -37,6 +37,33 @@ https://cursor.com/bugbot
 BugBot suggestions should be treated as recommendations, not blocking requirements — accuracy is still evolving and false positives can occur.
 
 
+## Warden
+
+[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. For a reference example, see [sentry-python's `warden.toml`](https://github.com/getsentry/sentry-python/blob/master/warden.toml).
+
+
 ## Tips for New Engineers
 
 - **Don't ignore AI reviews, but don't blindly follow them either.** Read the suggestions, apply what makes sense, and dismiss false positives.

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

@@ -1,7 +1,21 @@
 ---
 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 | When to Reach For It |
+|---|---|---|
+| **[AGENTS.md](/sdk/getting-started/templates/agents-md-template/)** | Always-loaded repo instructions | Every SDK repo — sets the baseline for all AI contributions |
+| **[Skills](/sdk/getting-started/ai-tools/skills/)** | Portable AI playbooks | Encode repeated workflows once, run them consistently |
+| **[dotagents](/sdk/getting-started/ai-tools/skills/#dotagents)** | Skills package manager | Share and version-lock skills across the team |
+| **[AI Code Review](/sdk/getting-started/ai-tools/code-review/)** | AI-powered PR feedback | Every PR — surfaces issues before human review |
+| Rules files | Workflow-specific instructions | Fixed conventions that vary by task or directory |
+
+Requirement levels (MUST/SHOULD) are defined in [Repository and Documentation Standards](/sdk/getting-started/standards/repository-docs) and [Review and CI Standards](/sdk/getting-started/standards/review-ci).

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

@@ -4,38 +4,69 @@ 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.
 
+Commit `agents.toml` and `agents.lock` so every engineer on the team gets the same skills automatically.
 
-### Sentry SDK Skills
+| 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 |
 
-Agent skills for managing feature development across Sentry SDKs, following the Agent Skills open format.
+## Available Skills
 
-https://github.com/getsentry/sdk-skills/
+### Sentry Skills
 
+Agent skills for Sentry employees, covering general workflows like committing, opening PRs, code review, finding bugs, and security review.
 
-### Sentry Reproduction Skill (repro)
+https://github.com/getsentry/skills
 
-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.
+### Sentry SDK Skills
 
-https://github.com/getsentry/repro
+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/standards/repository-docs.mdx

@@ -1,11 +1,14 @@
 ---
 title: Repository and Documentation
 spec_id: sdk/getting-started/standards/repository-docs
-spec_version: 1.0.0
+spec_version: 1.1.0
 spec_status: candidate
 spec_platforms:
   - all
 spec_changelog:
+  - version: 1.1.0
+    date: 2026-03-06
+    summary: Add AI Skills SHOULD requirement (dotagents + rules files)
   - version: 1.0.0
     date: 2026-02-19
     summary: Initial Repository and Documentation standard
@@ -154,6 +157,33 @@ AI context files (AGENTS.md, `.cursorrules`, `.github/copilot-instructions.md`,
 
 ---
 
+<SpecSection id="ai-skills" status="candidate" since="1.1.0">
+
+## AI Skills
+
+#### Rule
+
+SDK repos **SHOULD** have dotagents configured with skills from [`getsentry/skills`](https://github.com/getsentry/skills) and [`getsentry/sdk-skills`](https://github.com/getsentry/sdk-skills). Commit `agents.toml` and `agents.lock` so every engineer on the team gets the same skills automatically.
+
+Rules files (e.g. `.claude/rules/`, `.cursor/rules/`) **SHOULD** be used for fixed workflow conventions that apply to a specific task or directory.
+
+#### Enforcement
+
+- `agents.toml` / `agents.lock` presence in repo
+- Human review
+
+#### Suggested skill(s)
+
+- [`sentry-skills:agents-md`](https://github.com/getsentry/skills#available-skills)
+
+#### Per-SDK override
+
+<StatusBadge type="yes" /> Which skills are active and which rules files exist are SDK-specific.
+
+</SpecSection>
+
+---
+
 ## Changelog
 
 <SpecChangelog />

develop-docs/sdk/getting-started/standards/review-ci.mdx

@@ -1,11 +1,14 @@
 ---
 title: Review and CI
 spec_id: sdk/getting-started/standards/review-ci
-spec_version: 1.0.0
+spec_version: 1.1.0
 spec_status: candidate
 spec_platforms:
   - all
 spec_changelog:
+  - version: 1.1.0
+    date: 2026-03-06
+    summary: Add Warden SHOULD requirement
   - version: 1.0.0
     date: 2026-02-19
     summary: Initial Review and CI standard
@@ -171,6 +174,31 @@ See also: [Setting up release infrastructure playbook](/sdk/getting-started/play
 
 ---
 
+<SpecSection id="warden" status="candidate" since="1.1.0">
+
+## Warden
+
+#### Rule
+
+SDK repos **SHOULD** have [Warden](https://warden.sentry.dev/) configured in CI via the Warden GitHub Action. Warden runs AI-powered skills against PR diffs to enforce SDK-specific conventions that static linters cannot express.
+
+#### Enforcement
+
+- GitHub Actions (Warden GitHub Action)
+- Human review for follow-up on findings
+
+#### Suggested skill(s)
+
+- [`sentry-skills:warden-lint-judge`](https://github.com/getsentry/skills#available-skills) — converts findings into permanent lint rules.
+
+#### Per-SDK override
+
+<StatusBadge type="yes" /> Which Warden skills are active varies per SDK.
+
+</SpecSection>
+
+---
+
 ## Changelog
 
 <SpecChangelog />

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

@@ -1,10 +1,71 @@
 ---
 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/main/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
+
+Use the [`sentry-skills:agents-md`](https://github.com/getsentry/skills/blob/main/plugins/sentry-skills/skills/agents-md/SKILL.md) skill to generate initial content from your codebase — it follows the structure below and pulls in real conventions from your repo.
+
+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/
+```