mirror of https://github.com/getsentry/sentry-for-ai.git synced 2026-09-14 14:28:22 +08:00

Files

T

Evan Purkhiser d65bd23b67 feat(dist): build and publish per-agent plugin distributions (#158 )

This repository is the single source of truth for skills and routing metadata,
but it is not itself an installable plugin, and each assistant (Claude Code,
Cursor, Codex, Grok) expects the plugin in a different on-disk shape. No plugin
ecosystem can consume a zip or release asset; all install from a git ref. So a
GitHub Actions workflow builds each agent's distribution from this repository
and deploys it to a dedicated repository whose root is exactly that agent's
plugin, which a marketplace points at as getsentry/plugin-<agent>.

Each agent has a `plugin-src/<agent>/` dir with its manifests, README, and a
`build.sh` that assembles the dist tree from shared repo content. Claude, Cursor,
and Grok consume the plugin at the repo root; Codex requires it under
`plugins/sentry/` and rejects the `disable-model-invocation` field the skill
tree relies on, so its build strips that field and emits a per-skill
`agents/openai.yaml` (see `hide-skills.py`). MCP config is built from the repo's
`mcp.json` source of truth: inline in Claude's manifest, and a file for the
others.

Cross-repo writes use a short-lived token from a dedicated GitHub App scoped to
contents:write on the plugin repos; the default GITHUB_TOKEN cannot push to
other repositories.

The root `.claude-plugin/`, `.cursor-plugin/`, and `.mcp.json` are retained so
existing installs that consumed the plugin from this repo's root keep working;
their READMEs announce removal on or after 2026-07-11.

2026-06-12 13:39:38 -04:00

6.7 KiB

Raw Permalink Blame History

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-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

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:

Create skills/<skill-name>/SKILL.md with standard frontmatter
Add category, parent, disable-model-invocation: true to frontmatter
Add breadcrumb as first body line: > [All Skills](../../SKILL_TREE.md) > [Category](../router/SKILL.md) > Skill Name
Add the skill to the parent router's routing table
Run scripts/build-skill-tree.sh to regenerate SKILL_TREE.md and validate
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

6.7 KiB Raw Permalink Blame History