mirror of https://github.com/getsentry/sentry-agent-skills.git synced 2026-09-20 14:23:25 +08:00

T

Daniel Griesser 77d210f0ad feat: add sentry-nextjs-sdk skill bundle (#18 )

* feat(sentry-nextjs-sdk): add main SKILL.md wizard

Implements the four-phase wizard for the sentry-nextjs-sdk skill bundle,
covering all three Next.js runtimes (browser, Node.js server, Edge).

Phase 1 detects the project's router type (App Router vs Pages Router),
existing Sentry config, Next.js version, and companion backends.

Phase 2 recommends Error Monitoring + Tracing + Session Replay as the
opinionated baseline, with Logging and Profiling as optional extras.

Phase 3 guides setup with:
- Option 1: Wizard (Recommended) — `npx @sentry/wizard@latest -i nextjs`
  with auth flow + source map benefits described (PR #17 pattern)
- Option 2: Manual Setup — complete instructions for all three init files
  (`instrumentation-client.ts`, `sentry.server.config.ts`,
  `sentry.edge.config.ts`) plus `instrumentation.ts` registration hook,
  App Router `global-error.tsx`, Pages Router `_error.tsx`, and
  `withSentryConfig()` wrapper
- Source maps coverage in the main file (not a reference), with env var
  setup, .gitignore note, and `authToken` wiring
- Reference dispatch table for Error Monitoring, Tracing, Session Replay,
  Logging, and Profiling reference files

Phase 4 cross-links companion backend SDKs (Go, Python, Ruby, Java, Node)
with distributed tracing context.

Also includes: init options reference table, env vars table, verification
checklist, and 8-entry troubleshooting table covering common issues
(minified stack traces, missing edge errors, tunnel 404s, Turbopack
tree-shaking conflicts).

* feat(nextjs-sdk): add error-monitoring.md reference

Adds a comprehensive error monitoring reference for the sentry-nextjs-sdk
skill covering all three Next.js runtimes (browser, Node.js, Edge).

Key sections:
- Three-runtime architecture overview with init file mapping table
- Automatic vs manual capture decision table with the core rule explained
- Client-side: captureException, captureMessage, unhandled rejections
- Error boundaries: app/error.tsx, app/global-error.tsx (App Router),
  pages/_error.tsx + _app.tsx (Pages Router), Sentry.ErrorBoundary for
  React 18 and earlier, reactErrorHandler() for React 19+
- Server-side: onRequestError hook (SDK ≥8.28.0 + Next.js 15+), API routes
  for both routers, Server Actions (manual and withServerActionInstrumentation)
- Edge runtime: sentry.edge.config.ts, middleware pattern, tunnel route exclusion
- Scope management: global/isolation/current scopes with decision guide
- Event enrichment: setTag/setTags, setContext, setUser, setExtra with
  searchability/indexing comparison table
- Breadcrumbs: automatic capture table, manual addBreadcrumb with full
  property reference, beforeBreadcrumb filter/mutate pattern
- beforeSend / beforeSendTransaction / ignoreErrors / allowUrls / denyUrls
- Fingerprinting: per-event, withScope, beforeSend patterns with template vars
- Event processors (multiple allowed, unlike beforeSend)
- Scenario coverage table (which errors are auto vs manual)
- API quick reference cheat sheet
- Troubleshooting table with 10 common issues

* docs(sentry-nextjs-sdk): add tracing.md and profiling.md references

Add two deep-dive reference files for the sentry-nextjs-sdk skill:

**tracing.md** (616 lines) covers:
- SDK activation: all three runtime configs must have tracesSampleRate/tracesSampler
- tracesSampleRate uniform sampling with environment-aware patterns
- tracesSampler with SamplingContext shape, route-based examples, inheritOrSampleWith
- Auto-instrumented operations: browser (pageload, navigation, fetch, INP, LoAF) and
  server (API routes, RSC, getServerSideProps, Edge middleware)
- browserTracingIntegration full options table
- Custom spans: startSpan, startSpanManual, startInactiveSpan, setActiveSpanInBrowser
- Span options reference with common op values table
- Span enrichment: setAttribute, setStatus, updateSpanName, beforeSendSpan
- Server Actions: withServerActionInstrumentation() with full options table
- Distributed tracing: sentry-trace/baggage headers, tracePropagationTargets,
  automatic SSR→client trace continuation, manual propagation for non-HTTP channels
- Advanced APIs: continueTrace, startNewTrace, suppressTracing, withActiveSpan,
  forceTransaction, onlyIfParent, browser flat span hierarchy
- Complete three-runtime config example
- Troubleshooting table with 11 common issues

**profiling.md** (385 lines) covers:
- Browser vs Node.js profiling runtimes and what each captures
- How profiling attaches to traces (compound sampling formula)
- Browser: Chromium-only limitation, Document-Policy header requirement
  with platform-specific setup (Next.js headers, Vercel, Netlify, Nginx)
- Browser SDK config: trace mode and manual mode with uiProfiler
- Node.js: @sentry/profiling-node install, version pinning requirement,
  nodeProfilingIntegration, trace mode and manual mode with profiler
- Supported platforms table (OS × arch × Node version)
- Environment variables for binary path and logging mode
- Configuration parameters reference table
- profileSessionSampleRate session-level semantics
- profileLifecycle modes comparison table
- Production vs development recommendations with performance impact notes
- Chrome DevTools conflict warning
- Complete four-file setup example (client, server, edge, next.config.ts)
- Troubleshooting table with 12 common issues

* feat(sentry-nextjs-sdk): add logging, session-replay, ai-monitoring, and crons references

Four deep-dive reference files for the sentry-nextjs-sdk skill:

**logging.md** (~280 lines)
- Three-runtime configuration requirement (client, server, edge)
- Full Sentry.logger API (trace/debug/info/warn/error/fatal) with attribute types
- Parameterized messages via logger.fmt tagged template literal
- consoleLoggingIntegration with console→Sentry level mapping
- beforeSendLog filtering hook with log object shape
- Scope-based attributes (getGlobalScope vs getIsolationScope) with
  Next.js-specific warning about cross-request isolation on the server
- Third-party integrations: Pino, Consola, Winston
- Auto-generated attributes table, wide events best practice
- Version matrix and troubleshooting table

**session-replay.md** (~330 lines)
- instrumentation-client.ts placement with explicit "where NOT to add" table
- Sample rate semantics and recommended values by traffic tier
- Session lifecycle (5min inactivity, 60min max)
- Full replayIntegration() options reference (general + network capture)
- Privacy masking: mask/block/ignore mechanisms with HTML attribute/class table
- v8 breaking change note for unblock/unmask defaults
- Network capture with limits (150k chars, text-only bodies)
- Tree-shaking via withSentryConfig (webpack only, Turbopack unsupported)
- Canvas recording with WebGL/3D manual snapshot mode
- Lazy loading, programmatic control, custom compression worker
- CSP requirements with Next.js headers() example
- Performance impact notes and troubleshooting table

**ai-monitoring.md** (~290 lines)
- Supported libraries table: OpenAI, Vercel AI SDK, Anthropic with auto-enable status
- OpenAI: server-side openAIIntegration() vs manual instrumentOpenAiClient()
  with critical streaming note (stream_options: { include_usage: true })
- Vercel AI SDK: force: true requirement for Vercel production deployments,
  per-call experimental_telemetry opt-in requirement
- Anthropic: server auto-enable and manual instrumentAnthropicAiClient()
- Token usage attributes following OpenTelemetry GenAI semantic conventions
- PII controls (recordInputs/recordOutputs with sendDefaultPii interaction)
- Complete three-integration setup example with Route Handler examples
- AI Agents dashboard overview (Overview/Models/Tools/Traces tabs)
- Version matrix and troubleshooting table

**crons.md** (~250 lines)
- Four approaches: Vercel auto-monitors, cron library instrumentation,
  withMonitor() wrapper, manual captureCheckIn()
- Critical note: automaticVercelMonitors only works with Pages Router,
  NOT App Router route handlers
- Auto-instrumentation for cron, node-cron, node-schedule packages
- Full MonitorConfig interface (crontab/interval schedule, checkinMargin,
  maxRuntime, timezone, failureIssueThreshold, recoveryThreshold)
- App Router Route Handler and Edge runtime examples
- Rate limit (6 check-ins/min/environment) and alerting notes
- Version matrix and troubleshooting table

* docs(readme): add sentry-nextjs-sdk to Available Skills

Register the new Next.js SDK skill bundle in the README's SDK Skills table
and the 'When to Use Which Skill' quick-reference section.

Table entry covers the full feature set: error monitoring, tracing, profiling,
logging, session replay, AI monitoring, and crons — with App Router + Pages
Router support noted and a link to the official Next.js guide.

Three trigger phrases added to the quick-reference: general Next.js setup,
App Router-specific setup, and AI/OpenAI monitoring in Next.js.

* fix(sentry-nextjs-sdk): address P1/P2 review findings across skill and references

Fix six issues identified in code review:

P1 fixes:
- Add AI Monitoring and Crons to Phase 2 recommendation list (optional enhanced
  observability), with matching rows in the Phase 3 reference dispatch table and
  updated frontmatter description to include the two new features
- Replace NEXT_PUBLIC_SENTRY_DSN with SENTRY_DSN in all sentry.server.config.ts
  and sentry.edge.config.ts code blocks in ai-monitoring.md (6 occurrences) and
  logging.md (server + edge blocks in the three-runtime example); client-side
  instrumentation-client.ts blocks correctly retain NEXT_PUBLIC_SENTRY_DSN
- Replace deprecated sentry.client.config.ts file name with instrumentation-client.ts
  in logging.md (combined header comment at line ~16 and the three-runtime section
  at line ~266)

P2 fixes:
- Add Metrics to Phase 2 optional list with description and recommendation logic row
- Remove cross-link to non-existent sentry-java-sdk skill; replace with a direct
  link to docs.sentry.io/platforms/java/
- Update session-replay.md opening warning to drop the legacy sentry.client.config.ts
  mention, keeping only instrumentation-client.ts as the correct client config file

* fix(nextjs-sdk): correct DSN variable in server-side logging examples

Replace NEXT_PUBLIC_SENTRY_DSN with SENTRY_DSN in the two remaining
server-side code blocks in logging.md:

- The 'Enabling Logs' combined example now annotates per-runtime DSN usage
  and defaults to SENTRY_DSN with a comment for client config
- The Pino integration example now correctly uses SENTRY_DSN and notes
  it belongs in sentry.server.config.ts (Node.js server-side only)

These were the last two DSN inconsistencies flagged by the reviewer.

2026-02-27 10:57:30 +01:00

.github/workflows

chore: remove deprecated setup skills superseded by SDK bundles (#14 )

2026-02-26 22:07:05 +01:00

docs

Wizard-first setup guidance for frontend/mobile SDK skills (#17 )

2026-02-27 09:23:39 +01:00

scripts

chore: remove deprecated setup skills superseded by SDK bundles (#14 )

2026-02-26 22:07:05 +01:00

skills

feat: add sentry-nextjs-sdk skill bundle (#18 )

2026-02-27 10:57:30 +01:00

AGENTS.md

chore: remove legacy setup skills and size-restricting guidelines (#11 )

2026-02-26 18:36:39 +01:00

README.md

feat: add sentry-nextjs-sdk skill bundle (#18 )

2026-02-27 10:57:30 +01:00

README.md

Sentry Agent Skills

Official agent skills for integrating Sentry into your projects. These skills provide AI coding assistants with the knowledge to set up Sentry, debug production issues, and leverage Sentry's full observability platform.

Available Skills

SDK Skills (Full Platform Bundles)

Skill	Description	Platforms	Docs
`sentry-go-sdk`	Full Sentry setup wizard for Go — error monitoring, tracing, logging, metrics, crons	Go (net/http, Gin, Echo, Fiber)	Go Guide
`sentry-python-sdk`	Full Sentry setup wizard for Python — error monitoring, tracing, profiling, logging, metrics, crons, AI monitoring	Python (Django, Flask, FastAPI, Celery, Starlette, AIOHTTP)	Python Guide
`sentry-svelte-sdk`	Full Sentry setup wizard for Svelte/SvelteKit — error monitoring, tracing, session replay, logging	Svelte, SvelteKit	SvelteKit Guide
`sentry-ruby-sdk`	Full Sentry setup wizard for Ruby — error monitoring, tracing, logging, Sidekiq metrics + dashboard, migration from AppSignal/Honeybadger	Ruby, Rails, Sinatra, Rack, Sidekiq	Ruby Guide
`sentry-cocoa-sdk`	Full Sentry setup wizard for Apple platforms — error monitoring, tracing, profiling, session replay, logging	iOS, macOS, tvOS, watchOS, visionOS (Swift, UIKit, SwiftUI)	Apple Guide
`sentry-react-native-sdk`	Full Sentry setup wizard for React Native and Expo — error monitoring, tracing, profiling, session replay, logging, native crash symbolication	React Native, Expo managed/bare	React Native Guide
`sentry-react-sdk`	Full Sentry setup wizard for React — error monitoring, tracing, session replay, profiling, logging	React 16+, React Router v5-v7, TanStack Router, Redux, Vite, webpack	React Guide
`sentry-nextjs-sdk`	Full Sentry setup wizard for Next.js — error monitoring, tracing, profiling, logging, session replay, AI monitoring, crons	Next.js App Router + Pages Router, Vercel, `@sentry/nextjs`	Next.js Guide

Setup Skills

Skill	Description	Platforms	Docs
`sentry-setup-ai-monitoring`	Setup Sentry AI Agent Monitoring	JS, Python	AI Monitoring

Workflow Skills

Skill	Description	Requirements	Docs
`sentry-fix-issues`	Find and fix issues from Sentry using MCP	Sentry MCP	Issues
`sentry-pr-code-review`	Review a project's PRs to check for issues detected in code review by Seer Bug Prediction	GitHub CLI	Seer
`sentry-create-alert`	Create Sentry alerts using the workflow engine API	`curl`, auth token	Alerts

Authoring Skills

Skill	Description	Requirements
`sentry-sdk-skill-creator`	Create a complete SDK skill bundle for any new platform — research, write, verify, and register	Web search, `claude` tool

Installation

Quick Install (Recommended)

Install all skills using the skills CLI:

npx skills add https://github.com/getsentry/sentry-agent-skills

Or install a specific skill:

npx skills add https://github.com/getsentry/sentry-agent-skills --skill sentry-fix-issues

Browse available skills at skills.sh/getsentry/sentry-agent-skills.

Manual Installation

Choose your AI coding assistant below and run the appropriate command.

Claude Code

User-level (applies to all projects):

git clone https://github.com/getsentry/sentry-agent-skills.git /tmp/sentry-skills && \
  mkdir -p ~/.claude/skills && \
  cp -r /tmp/sentry-skills/skills/* ~/.claude/skills/ && \
  rm -rf /tmp/sentry-skills

Project-level (single repository):

git clone https://github.com/getsentry/sentry-agent-skills.git /tmp/sentry-skills && \
  mkdir -p .claude/skills && \
  cp -r /tmp/sentry-skills/skills/* .claude/skills/ && \
  rm -rf /tmp/sentry-skills

Directory structure

~/.claude/skills/              # User-level
.claude/skills/                # Project-level

# Each skill:
sentry-fix-issues/
  SKILL.md

OpenAI Codex

User-level (applies to all projects):

git clone https://github.com/getsentry/sentry-agent-skills.git /tmp/sentry-skills && \
  mkdir -p ~/.codex/skills && \
  cp -r /tmp/sentry-skills/skills/* ~/.codex/skills/ && \
  rm -rf /tmp/sentry-skills

Project-level (single repository):

git clone https://github.com/getsentry/sentry-agent-skills.git /tmp/sentry-skills && \
  mkdir -p .codex/skills && \
  cp -r /tmp/sentry-skills/skills/* .codex/skills/ && \
  rm -rf /tmp/sentry-skills

Directory structure

~/.codex/skills/               # User-level
.codex/skills/                 # Project-level

# Each skill:
sentry-fix-issues/
  SKILL.md

GitHub Copilot

User-level (applies to all projects):

git clone https://github.com/getsentry/sentry-agent-skills.git /tmp/sentry-skills && \
  mkdir -p ~/.copilot/skills && \
  cp -r /tmp/sentry-skills/skills/* ~/.copilot/skills/ && \
  rm -rf /tmp/sentry-skills

Project-level (single repository):

git clone https://github.com/getsentry/sentry-agent-skills.git /tmp/sentry-skills && \
  mkdir -p .github/skills && \
  cp -r /tmp/sentry-skills/skills/* .github/skills/ && \
  rm -rf /tmp/sentry-skills

Directory structure

~/.copilot/skills/             # User-level
.github/skills/                # Project-level

# Each skill:
sentry-fix-issues/
  SKILL.md

Cursor

Note: Agent skills require Cursor Nightly. Enable via: Cursor Settings > Rules > Import Settings > Agent Skills

User-level (applies to all projects):

git clone https://github.com/getsentry/sentry-agent-skills.git /tmp/sentry-skills && \
  mkdir -p ~/.cursor/skills && \
  cp -r /tmp/sentry-skills/skills/* ~/.cursor/skills/ && \
  rm -rf /tmp/sentry-skills

Project-level (single repository):

git clone https://github.com/getsentry/sentry-agent-skills.git /tmp/sentry-skills && \
  mkdir -p .cursor/skills && \
  cp -r /tmp/sentry-skills/skills/* .cursor/skills/ && \
  rm -rf /tmp/sentry-skills

Directory structure

~/.cursor/skills/              # User-level
.cursor/skills/                # Project-level

# Each skill:
sentry-fix-issues/
  SKILL.md

OpenCode

User-level (applies to all projects):

git clone https://github.com/getsentry/sentry-agent-skills.git /tmp/sentry-skills && \
  mkdir -p ~/.config/opencode/skill && \
  cp -r /tmp/sentry-skills/skills/* ~/.config/opencode/skill/ && \
  rm -rf /tmp/sentry-skills

Project-level (single repository):

git clone https://github.com/getsentry/sentry-agent-skills.git /tmp/sentry-skills && \
  mkdir -p .opencode/skill && \
  cp -r /tmp/sentry-skills/skills/* .opencode/skill/ && \
  rm -rf /tmp/sentry-skills

Directory structure

~/.config/opencode/skill/      # User-level
.opencode/skill/               # Project-level

# Also supports Claude-compatible paths:
~/.claude/skills/              # User-level (alternative)
.claude/skills/                # Project-level (alternative)

# Each skill:
sentry-fix-issues/
  SKILL.md

AmpCode (Sourcegraph Amp)

User-level (applies to all projects):

git clone https://github.com/getsentry/sentry-agent-skills.git /tmp/sentry-skills && \
  mkdir -p ~/.config/agents/skills && \
  cp -r /tmp/sentry-skills/skills/* ~/.config/agents/skills/ && \
  rm -rf /tmp/sentry-skills

Project-level (single repository):

git clone https://github.com/getsentry/sentry-agent-skills.git /tmp/sentry-skills && \
  mkdir -p .agents/skills && \
  cp -r /tmp/sentry-skills/skills/* .agents/skills/ && \
  rm -rf /tmp/sentry-skills

Directory structure

~/.config/agents/skills/       # User-level
.agents/skills/                # Project-level

# Also supports Claude-compatible paths:
~/.claude/skills/              # User-level (alternative)
.claude/skills/                # Project-level (alternative)

# Each skill:
sentry-fix-issues/
  SKILL.md

Quick Reference

Client	User-Level Path	Project-Level Path
Claude Code	`~/.claude/skills/`	`.claude/skills/`
Codex	`~/.codex/skills/`	`.codex/skills/`
Copilot	`~/.copilot/skills/`	`.github/skills/`
Cursor	`~/.cursor/skills/`	`.cursor/skills/`
OpenCode	`~/.config/opencode/skill/`	`.opencode/skill/`
AmpCode	`~/.config/agents/skills/`	`.agents/skills/`

Usage

Once installed, your AI assistant will automatically discover the skills. Simply ask:

SDK Skills (Full Platform Bundles)

What to Say	Skill Used
"Add Sentry to my Go app"	`sentry-go-sdk`
"Set up Sentry in my Gin/Echo/Fiber project"	`sentry-go-sdk`
"Add Sentry to my Python app"	`sentry-python-sdk`
"Set up Sentry in my Django/Flask/FastAPI project"	`sentry-python-sdk`
"Monitor my OpenAI/LangChain calls in Python"	`sentry-python-sdk`
"Add Sentry to my SvelteKit app"	`sentry-svelte-sdk`
"Set up Sentry in Svelte"	`sentry-svelte-sdk`
"Add Sentry to my Ruby/Rails app"	`sentry-ruby-sdk`
"Set up Sentry metrics for Puma/Sidekiq"	`sentry-ruby-sdk`
"Migrate from AppSignal to Sentry"	`sentry-ruby-sdk`
"Replace Honeybadger with Sentry"	`sentry-ruby-sdk`
"Add Sentry to my iOS app"	`sentry-cocoa-sdk`
"Set up Sentry in my Swift/SwiftUI project"	`sentry-cocoa-sdk`
"Add Sentry to my macOS app"	`sentry-cocoa-sdk`
"Add Sentry to my React Native app"	`sentry-react-native-sdk`
"Set up Sentry in Expo"	`sentry-react-native-sdk`
"Configure session replay for React Native"	`sentry-react-native-sdk`
"Add Sentry to my React app"	`sentry-react-sdk`
"Set up error boundaries in React"	`sentry-react-sdk`
"Configure session replay for React"	`sentry-react-sdk`
"Add Sentry to my Next.js app"	`sentry-nextjs-sdk`
"Set up Sentry in Next.js App Router"	`sentry-nextjs-sdk`
"Monitor AI/OpenAI calls in Next.js"	`sentry-nextjs-sdk`

Setup

What to Say	Skill Used
"Add Sentry to my iOS/Swift app"	`sentry-cocoa-sdk`
"Monitor my OpenAI/LangChain calls"	`sentry-setup-ai-monitoring`

Debugging & Workflow

What to Say	Skill Used
"Fix the recent Sentry errors"	`sentry-fix-issues`
"Debug the production TypeError"	`sentry-fix-issues`
"Work through my Sentry backlog"	`sentry-fix-issues`
"Review Sentry comments on PR #123"	`sentry-pr-code-review`
"Fix the issues Sentry found in my PR"	`sentry-pr-code-review`
"Create an alert that emails me when a high priority issue de-escalates"	`sentry-create-alert`
"Set up a Slack notification for new Sentry issues"	`sentry-create-alert`
`/sentry-create-alert`	`sentry-create-alert`

The assistant will load the appropriate skill and guide you through the process.

Skill Format

These skills follow the Agent Skills specification. Each skill contains:

skill-name/
  SKILL.md        # Required: YAML frontmatter + markdown instructions

SKILL.md structure:

---
name: skill-name
description: Description of what this skill does and when to use it
---

# Skill Title

Instructions for the AI assistant...

SDK skill bundles use a references/ directory for feature-specific deep dives:

sentry-go-sdk/
  SKILL.md           # Main wizard
  references/
    error-monitoring.md
    tracing.md
    ...

Contributing

Contributions are welcome! Please ensure any new skills:

Follow the Agent Skills specification
Have a valid name (lowercase letters, numbers, hyphens, 1-64 chars, no consecutive hyphens, must not start or end with hyphen)
Include a clear description (1-1024 chars)
Include an "Invoke This Skill When" section with trigger phrases
Verify technical details against Sentry docs

For full-platform SDK skills (covering all Sentry features for one language/framework), see docs/sdk-skill-philosophy.md for the bundle architecture pattern.

Style Guidelines

Prefer tables over paragraphs for reference information
Use phases/steps for multi-stage workflows
Include version requirements where applicable
Add troubleshooting tables for common issues
SDK skill bundles should be comprehensive — use references/ directories for deep-dive content loaded on demand

License

Apache-2.0