getsentry__sentry-for-ai/AGENTS.md

Agent Instructions

Project Overview

Sentry plugin for AI coding assistants (Claude Code, Cursor, Codex, and Grok). Provides MCP server integration, slash commands, and skills.

Commit Attribution

AI commits MUST include:

Co-Authored-By: (the agent model's name and attribution byline)

Plugin Structure

commands/               # Slash commands (/seer)
skills/                 # Setup and review skills
.agents/                # Symlinks to commands/ and skills/
.claude-plugin/         # Claude Code plugin metadata
.cursor-plugin/         # Cursor plugin metadata

Skills use YAML frontmatter with allowed-tools — this is required by Cursor and harmless in Claude Code. Keep it in all skill files.

Skills

SDK Skills (Full Platform Bundles)

Skill	Description
sentry-android-sdk	Full setup wizard for Android (Jetpack Compose, Views, OkHttp, Room, Fragment, Timber)
sentry-cloudflare-sdk	Full setup wizard for Cloudflare Workers and Pages (Durable Objects, D1, Queues, Workflows, Hono)
sentry-cocoa-sdk	Full setup wizard for Apple platforms (iOS, macOS, tvOS, watchOS, visionOS)
sentry-dotnet-sdk	Full setup wizard for .NET (ASP.NET Core, MAUI, WPF, WinForms, Azure Functions)
sentry-elixir-sdk	Full setup wizard for Elixir (Phoenix, Plug, LiveView, Oban, Quantum)
sentry-flutter-sdk	Full setup wizard for Flutter and Dart (Android, iOS, macOS, Linux, Windows, Web, Dio, sqflite, Hive, Isar, Drift)
sentry-go-sdk	Full setup wizard for Go (net/http, Gin, Echo, Fiber)
sentry-nestjs-sdk	Full setup wizard for NestJS (Express, Fastify, GraphQL, Microservices)
sentry-node-sdk	Full setup wizard for Node.js, Bun, and Deno (Express, Fastify, Koa, Hapi, Connect)
sentry-nextjs-sdk	Full setup wizard for Next.js (App Router + Pages Router)
sentry-php-sdk	Full setup wizard for PHP (Laravel, Symfony)
sentry-python-sdk	Full setup wizard for Python (Django, Flask, FastAPI, Celery)
sentry-react-native-sdk	Full setup wizard for React Native and Expo
sentry-browser-sdk	Full setup wizard for Browser JavaScript (vanilla JS, jQuery, WordPress, static sites, Loader Script, CDN)
sentry-react-sdk	Full setup wizard for React (Router v5-v7 non-framework mode, TanStack, Redux)
sentry-react-router-framework-sdk	Full setup wizard for React Router Framework mode (@sentry/react-router)
sentry-tanstack-start-sdk	Full setup wizard for TanStack Start React (router tracing, server entry instrumentation, Vite plugin, middleware)
sentry-ruby-sdk	Full setup wizard for Ruby (Rails, Sinatra, Sidekiq)
sentry-svelte-sdk	Full setup wizard for Svelte/SvelteKit

Setup Skills

Skill	Description
sentry-setup-ai-monitoring	Instrument OpenAI/Anthropic/Vercel AI/LangChain/Google GenAI
sentry-otel-exporter-setup	Setup OTel Collector with Sentry Exporter
sentry-span-streaming-js	Migrate JavaScript SDK from transaction-based to streamed span delivery
sentry-span-streaming-python	Migrate Python SDK from transaction-based to streamed span delivery
sentry-span-streaming-dart	Migrate Dart/Flutter SDK from transaction-based to streamed span delivery
sentry-instrumentation-guide	Decide which signal to reach for — error vs span vs log vs metric

Workflow Skills

Skill	Description
sentry-code-review	Analyze and resolve Sentry bot comments on GitHub PRs
sentry-pr-code-review	Review PRs for issues detected by Seer Bug Prediction
sentry-fix-issues	Find and fix Sentry issues using MCP
sentry-sdk-upgrade	Upgrade the Sentry JavaScript SDK across major versions
sentry-create-alert	Create Sentry alerts using the workflow engine API

Authoring Skills

Skill	Description
sentry-sdk-skill-creator	Create a complete SDK skill bundle for any new platform

Commands

Command	Description
/seer <query>	Natural language Sentry environment queries

MCP Server

Sentry MCP server configured at https://mcp.sentry.dev/mcp. The source of truth is mcp.json: Cursor consumes it as-is at the plugin root, while the Codex and Grok builds emit it as .mcp.json (Codex's validator requires the dotted name; Grok auto-discovers it). Claude declares the server inline in its plugin.json (mcpServers), so the Claude build ships no MCP file. The root .mcp.json is a backwards-compat copy (identical to mcp.json) retained for existing installs that consumed the plugin from this repo's root; keep the two in sync until the root compat surface is removed.

Key Conventions

• All setup skills must detect platform/SDK before suggesting configuration — never assume
• Sentry code review skill only processes comments from sentry[bot], ignores other bots
• GitHub CLI (gh) required for PR-related skills
• Avoid emojis in skill/command content — keep output platform-neutral

Skill Tree Navigation

How it works:

• 3 router skills (always visible in agent metadata): sentry-sdk-setup, sentry-workflow, sentry-feature-setup
• All other skills are hidden with disable-model-invocation: true — loaded on-demand when a router points to them
• SKILL_TREE.md at repo root is the flat sitemap listing every skill
• This keeps startup metadata at ~300 tokens instead of ~1,600+ as the library grows
• Tools that don't support disable-model-invocation simply see all skills (same as before)

Categories:

• sdk-setup — platform/language SDK setup wizards (router: sentry-sdk-setup)
• workflow — debugging, code review, issue management (router: sentry-workflow)
• feature-setup — specific feature configuration (router: sentry-feature-setup)
• internal — contributor tools, no router

Adding a new skill:

1. Create skills/<skill-name>/SKILL.md with standard frontmatter
2. Add category, parent, disable-model-invocation: true to frontmatter
3. Add breadcrumb as first body line: > [All Skills](../../SKILL_TREE.md) > [Category](../router/SKILL.md) > Skill Name
4. Add the skill to the parent router's routing table
5. Run scripts/build-skill-tree.sh to regenerate SKILL_TREE.md and validate
6. CI validates automatically on every PR

Adding a new category:

• When a category exceeds ~10 skills, consider splitting
• Create a new router skill with role: router in frontmatter
• Update existing skills' category and parent fields
• Update this file to document the new category

Validation:

• scripts/build-skill-tree.sh — regenerates SKILL_TREE.md, validates all frontmatter, breadcrumbs, and router tables
• scripts/build-skill-tree.sh --check — CI mode, fails if SKILL_TREE.md is stale or validation errors exist