* docs(flutter-sdk): add profiling, logging, metrics, session-replay references
Add four reference files for the Flutter SDK skill covering features that
require precise documentation of platform constraints and limitations:
- profiling.md: iOS/macOS only, Alpha status, SDK ≥7.12.0. Documents the
profilesSampleRate/tracesSampleRate relationship, simulator vs. real device
caveats, Dart symbol upload requirements, and troubleshooting table.
- logging.md: Two paths — direct Sentry.logger API (SDK ≥9.5.0) and the
sentry_logging integration bridging the Dart logging package. Documents
LoggingIntegration configuration params (minBreadcrumbLevel, minEventLevel,
minSentryLogLevel), stack trace gotchas with Logger.root, scope-level
attributes via withScope, beforeSendLog filtering, and trace correlation.
- metrics.md: Open Beta, SDK ≥9.11.0 for trace-connected metrics. Honest about
the missing 'set' type, 2 KB per-metric key limit, and no per-metric sampling.
Covers all three supported types (counter/distribution/gauge) with unit
enums, tag constraints, and practical Dart examples.
- session-replay.md: iOS/Android only (not Web/macOS/Linux/Windows), SDK ≥9.0.0,
~1 fps screenshot-based capture. Documents options.replay.* and
options.privacy.* APIs, SentryWidget requirement, third-party widget masking
requirement, session lifecycle (30s background timeout, 60 min max),
performance overhead benchmarks, and full troubleshooting table.
All files follow the established React Native SDK reference format with a
minimum SDK version header, TOC, real Dart/Flutter code examples, honest
limitation sections, and troubleshooting tables.
Co-Authored-By: Claude Sonnet 4.6 (Anthropic)
* docs(flutter-sdk): add error-monitoring and tracing reference files
Complete the Flutter SDK skill reference library by adding the two
remaining deep-dive files referenced in the main SKILL.md but missing
from the initial commit.
error-monitoring.md:
- Documents all auto-captured error sources (FlutterError.onError,
PlatformDispatcher, Android NDK, iOS/macOS Mach exceptions)
- captureException / captureMessage / captureFeedback APIs with examples
- Scope management: configureScope, withScope, scope sync to native
- Breadcrumb capture and filtering via beforeBreadcrumb
- Event filtering with beforeSend (incl. honest note that it doesn't
intercept native crashes)
- Isolate error capture pattern (addSentryErrorListener)
- Attachments: screenshot, view hierarchy, file upload
- Android/iOS native crash options (tombstone, NDK sync, ANR, watchdog)
- Release health session tracking options
- Troubleshooting table
tracing.md:
- Setup: tracesSampleRate vs tracesSampler with sampling precedence order
- Navigation: SentryNavigatorObserver for MaterialApp, GoRouter, Auto Route
with honest limitations (GoRouter tabs, Auto Route nested nav)
- TTID (always on) vs TTFD (opt-in) with both setup patterns
- User interaction tracing: Key requirement, idle timeout, PII opt-in
- HTTP tracing: SentryHttpClient and sentry_dio with distributed tracing
config (tracePropagationTargets, propagateTraceparent)
- App start instrumentation: iOS/Android only, add-to-app caveat, disable path
- Slow/frozen frames: SentryWidgetsFlutterBinding workaround
- Custom instrumentation: transactions, nested spans, span data, dynamic sampling
- All four DB integrations: sqflite, Drift, Hive, Isar with setup snippets
- Asset bundle instrumentation
- Production config pattern with dynamic sampler
- Troubleshooting table including gRPC Windows issue
Co-Authored-By: Claude Sonnet 4.5 (Anthropic)
* docs(agents): add sentry-flutter-sdk to SDK skills table
* fix(flutter-sdk): address review findings — API consistency and version accuracy
- Fix enableLogs version: ≥9.0.0 → ≥9.5.0 in SKILL.md (matches logging.md)
- Replace fabricated Sentry.startSpan() with verified Sentry.startTransaction()
in logging.md and metrics.md trace correlation examples
- Fix Sentry.withScope() → Sentry.configureScope() in logging.md (correct Dart API)
- Add flutter-sdk keywords to build-skill-tree.sh Quick Lookup mapping
- Regenerate SKILL_TREE.md with proper keywords
* fix(flutter-sdk): remove fabricated cardinality claims from metrics reference
The 2 KB per-metric key limit is real, but the cardinality warnings,
'silently dropped' claims, and high-cardinality troubleshooting entry
were fabricated with no basis in Sentry docs or SDK source.
* fix(flutter-sdk): correct enableLogs version in Quick Reference section
Fix remaining ≥9.0.0 → ≥9.5.0 for enableLogs in the Quick Reference
code snippet. The earlier fix only caught the Phase 3 init block.
The docker commands used `<absolute_config_path>` while the surrounding
note referenced `<config_file>`, creating a disconnect that could cause
an AI agent to fail on path substitution. Use `<config_file>` consistently
since the note already explains how to make relative paths absolute.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The biggest reliability improvement came from changing the user's
prompt from 'read and follow: URL' to 'use curl to download, read
and follow: URL'. This bypasses WebFetch summarization entirely.
Make this discoverable:
- SKILL_TREE.md now opens with the exact prompt to copy-paste
- Entry points table shows /sdks, /workflows, /features shortcuts
- 'Why curl?' explanation for context
- Router skills shortened to use curl-first examples
- Individual skill fetching section moved below the entry points
Co-Authored-By: Claude Sonnet 4 (Anthropic)
Rewrite all three router skills (sentry-sdk-setup, sentry-workflow,
sentry-feature-setup) to work as self-contained entry points that
agents can land on directly, not just internal routing tables.
Each router now includes:
- 'How to Fetch Skills' section with URL pattern, example, and curl
hint for tools that summarize content
- 'Start Here' nudge telling agents to ask/confirm before acting
- Path column in tables showing exact fetchable paths as plain text
- Quick Lookup keyword table (SDK router) for fast platform matching
- Cross-link back to the full Skill Tree for other categories
- Fixed fetch URLs: removed incorrect /skills/ prefix from examples
These routers will be served directly via skills.sentry.gg at /sdks,
/workflows, and /features — giving agents a focused entry point when
they already know what category they need.
Co-Authored-By: Claude Sonnet 4 (Anthropic)
WebFetch and similar agent fetch tools often summarize long markdown
files instead of returning the full content. Sentry skill files are
10-20 KB of detailed configuration instructions — summaries lose
critical details like exact code snippets and config options.
Observed in a Claude Code session where WebFetch returned a 2,500-char
summary of an 18,000-char skill file twice before the agent figured out
to fall back to curl. Adding a one-line hint in the 'How to Fetch'
section saves agents from discovering this the hard way.
Co-Authored-By: Claude Sonnet 4 (Anthropic)
Rewrite the generated SKILL_TREE.md to help AI agents find and fetch
skills on the first try instead of guessing URLs, and to stop them from
rushing into action without understanding what the user wants.
Problem: agents read the SKILL_TREE, identify the platform they need,
then guess URL patterns (/nextjs, /sdk-setup/nextjs, etc.) instead of
following the markdown links — burning 4+ requests before finding the
correct path. They also skip the 'Start Here' section entirely and
immediately start installing packages and creating config files without
ever asking the user what they actually want.
Changes to build-skill-tree.sh:
- Replace 'How It Works' header with directive 'How to Fetch Skills'
section that puts the URL pattern front-and-center with an explicit
example
- Rewrite 'Start Here' as 'Start Here — Read This Before Doing
Anything' with explicit instructions to ask the user first, wait for
their answer, then fetch the matching skill. Tells agents not to
assume, not to skip, and not to improvise.
- Add a Path column to all skill tables showing the exact fetchable
path as plain-text code (e.g. `sentry-nextjs-sdk/SKILL.md`)
- Reorder table columns: description first (what agents match on),
then skill name, then path
- Add a Quick Lookup section at the bottom mapping common keywords
(nextjs, django, rails, etc.) to their skill paths — the grab-and-go
for agents that skim rather than parse tables
Co-Authored-By: Claude Sonnet 4 (Anthropic)
* feat(skill-tree): transform SKILL_TREE.md into agent-facing entry point
Rewrite SKILL_TREE.md from an internal plugin reference into the root
entry point for any AI agent accessing Sentry's skill library. When an
agent reads this file (via local install or https://skills.sentry.gg),
it now knows to introduce itself as Sentry's AI assistant, present the
user with options (SDK setup, debugging, features, code review, upgrade),
and dynamically load the matching skill.
Key changes:
- Agent persona and interactive greeting flow in 'Start Here' section
- Relative paths for all skill links (works on GitHub raw, web UI, and
local filesystem; proxy can serve them too)
- Base URL documented for skills.sentry.gg URL construction
- Platform Detection Priority section with disambiguation rules
- Dropped redundant 'Path' column from all tables
- Removed Internal section (contributor-only, not user-facing)
- Updated all 3 router skills to reference skills.sentry.gg URLs
instead of raw GitHub URLs in Dynamic Skill Fetching sections
- Updated build-skill-tree.sh to generate the new format
* chore: remove dead SKILLS_INTERNAL array
Addresses Bugbot review — the array was populated but never read
after the Internal section was removed from the generated output.
Internal skills are still validated, just not rendered.
* docs: reference skills.sentry.gg proxy in SKILL_TREE.md
Add a short paragraph explaining the proxy is available for clean URL
access, link to its source repo, and note that both path styles work.
Also fix the example URL to use the canonical form without the
skills/ prefix.
* feat(browser-sdk): add sentry-browser-sdk skill — vanilla JS, Loader Script, CDN
Adds the sentry-browser-sdk skill, a complete Sentry setup wizard for
browser JavaScript projects that don't use a framework-specific SDK.
## What's included
**SKILL.md (654 lines):**
- Phase 1: Framework detection FIRST — actively redirects React → sentry-react-sdk,
Next.js → sentry-nextjs-sdk, Vue/Angular/Svelte/Remix/Nuxt/Astro → their docs.
Only proceeds with @sentry/browser when no framework is detected.
- Three installation paths:
- Path A (npm): full setup with Sentry.init(), source maps via all four build
plugins (Vite, webpack, Rollup, esbuild) plus sentry-cli fallback
- Path B (Loader Script): for WordPress, Shopify, Squarespace, static HTML —
zero build tooling, lazy/eager modes, sentryOnLoad config, limitations
- Path C (CDN bundles): 7 named bundle variants with SRI integrity hashes for
manual script tag installs
- Phase 2: Feature recommendation matrix (Error Monitoring, Tracing, Replay,
User Feedback, Logging, Profiling) with npm-only callouts for Logging
- Phase 3: Reference dispatch table pointing to references/ subdirectory
- Configuration reference table (all Sentry.init() options)
- Verification section for all three paths
- Phase 4: Backend cross-link detection (Go, Python, Ruby, PHP, .NET, Node.js)
- Troubleshooting table (20+ issues with solutions)
**Router updates:**
- sentry-sdk-setup/SKILL.md: adds sentry-browser-sdk row and routing rule #9
(vanilla JS, jQuery, WordPress, static HTML → sentry-browser-sdk)
- AGENTS.md: adds sentry-browser-sdk to the SDK Skills table
- SKILL_TREE.md: regenerated via scripts/build-skill-tree.sh (0 errors)
Co-Authored-By: Claude Sonnet 4.6 (Anthropic)
* docs(sentry-browser-sdk): add error-monitoring, tracing, and session-replay reference files
Add three deep-dive reference documents to skills/sentry-browser-sdk/references/
covering the core feature pillars of the @sentry/browser SDK.
error-monitoring.md:
- Core capture APIs: captureException, captureMessage, captureEvent with full
parameter tables and real-world examples
- Three scope types (global / isolation / current) with usage guidance and
priority order
- Event enrichment: tags, context, user, extra, initialScope
- Breadcrumbs: automatic sources table, manual addBreadcrumb, beforeBreadcrumb
filtering with hint access
- Hooks: beforeSend, beforeSendTransaction with PII scrubbing and fingerprint
override examples
- Event processors vs. beforeSend comparison table
- Fingerprinting: extending vs. overriding default grouping, inline via
captureContext, fingerprint variable table
- Pattern-based filtering: ignoreErrors, allowUrls/denyUrls, sampleRate
- All 9 default integrations with config options
- Transport: offline IndexedDB queue, tunneling, custom transport
- 11-row troubleshooting table
tracing.md:
- Full browserTracingIntegration() options across five categories (page load,
HTTP, interaction, timeouts, propagation), each as a table
- Automatic instrumentation: pageloads, navigations, fetch/XHR, web vitals
(LCP, CLS, TTFB, INP), long tasks
- Custom span APIs: startSpan (auto-ending), startSpanManual, startInactiveSpan
with use-case guidance
- Span options table; operation types table; attribute and status APIs
- Distributed tracing: sentry-trace/baggage header propagation,
tracePropagationTargets rules, SSR meta tag continuation, non-HTTP channels
- Sampling: tracesSampleRate, tracesSampler with SamplingContext table,
precedence order, INP-specific sampling
- Custom router integration pattern using startBrowserTracingPageLoadSpan
- 10-row troubleshooting table
session-replay.md:
- replaysSessionSampleRate vs. replaysOnErrorSampleRate with sampling
workflow, data-sent matrix, and recommended rates by traffic volume
- Full replayIntegration() options across three sections (general, privacy,
network) with complete tables
- Privacy masking: three methods (mask/block/ignore), HTML attribute usage,
configuration examples, custom maskFn, beforeAddRecordingEvent filtering
- Network capture: opt-in body/header capture, truncation limit, deny/allow
URL rules
- Canvas recording: replayCanvasIntegration, manual snapshot mode for
WebGL/WebGPU, PII warning
- Lazy loading patterns for both npm (dynamic import) and CDN (lazyLoadIntegration)
- Session modes: session vs. buffer mode details, manual control API
(start/startBuffering/flush/stop/getReplayId)
- Deferred initialization, employee-only and URL-specific recording patterns
- Performance impact: mutation limits, self-hosted compression worker, CSP
requirements, bundler optimization
- 11-row troubleshooting table
All files use vanilla JS examples (no React, no JSX), include minimum SDK
version headers, and follow the same section structure and table formatting
used in skills/sentry-react-sdk/references/.
Co-Authored-By: Claude claude-sonnet-4-5 <noreply@anthropic.com>
* docs(browser-sdk): add profiling, logging, and user-feedback reference guides
Add three deep-dive reference files to skills/sentry-browser-sdk/references/:
**profiling.md**
- Prominently marks Beta status and Chromium-only limitation (Chrome/Edge;
Firefox and Safari are unsupported)
- Documents the mandatory Document-Policy: js-profiling header with
platform-specific examples for Vercel, Netlify, Express, and Nginx
- Covers profileSessionSampleRate (current, ≥10.27.0) vs the deprecated
profilesSampleRate, with a comparison table
- Explains manual vs trace profileLifecycle modes with code examples
- Production sampling strategy section and known limitations table
- 7-row troubleshooting table
**logging.md**
- Prominently marks npm-only limitation — NOT available via Loader Script or CDN
- Covers the full Sentry.logger.* API (trace/debug/info/warn/error/fatal)
with six-level table and attribute type constraints
- Documents logger.fmt parameterized template literals with attribute extraction
details and tagged-template gotcha warning
- consoleLoggingIntegration (≥10.13.0) for automatic console.* capture
- beforeSendLog filter hook with log object shape reference
- Scope-based automatic attributes (≥10.32.0) at global/isolation/current scopes
- Auto-generated attributes table including replay_id and trace linking
- Log-to-trace correlation example showing span ↔ log navigation in the UI
- When-to-use-each-API decision table and log level production guidance
- 10-row troubleshooting table
**user-feedback.md**
- Covers all three collection approaches: feedbackIntegration() widget,
captureFeedback() programmatic API, and showReportDialog() crash modal
- Full feedbackIntegration() option tables across appearance, form fields,
positioning, and behaviour categories
- Manual widget control (autoInject: false) with custom button example
- captureFeedback() with tags, attachments, and associatedEventId linking
- showReportDialog() with server-side event ID injection pattern for 500 pages
- Screenshot capture notes (≥8.0.0) and attachment quota callout
- Session Replay integration for replay-linked feedback (30-second buffer)
- Best practices covering proactive vs reactive collection
- 9-row troubleshooting table
Co-Authored-By: claude-sonnet-4-5 (Anthropic)
* fix(browser-sdk): correct Vue redirect and logging availability claims
Address review findings:
- P0: Fix copy-paste error in framework redirect table where Vue
incorrectly pointed to sentry-python-sdk instead of @sentry/vue.
Also remove duplicate nuxt entry from the vue row (nuxt already
has its own standalone row).
- P1: Reconcile logging availability — CDN bundles with .logs. in
their name (e.g. bundle.logs.metrics.min.js) DO support
Sentry.logger.*, so the blanket 'npm only' claim was inaccurate.
Updated to 'npm or CDN logs bundle; not Loader Script' across
SKILL.md and references/logging.md.
Co-Authored-By: Claude Sonnet 4 (Anthropic)
---------
Co-authored-by: Claude claude-sonnet-4-5 <noreply@anthropic.com>
* feat(php-sdk): add sentry-php-sdk main SKILL.md wizard
Add the primary wizard skill for PHP SDK setup covering plain PHP, Laravel, and
Symfony in a single skill following the one-skill-per-language pattern used by
Python, Ruby, and .NET skills.
The wizard follows the standard 4-phase structure:
- Phase 1 (Detect): composer.json inspection, filesystem markers (artisan /
bin/console), framework and queue detection
- Phase 2 (Recommend): concrete proposal matrix for Error Monitoring, Tracing,
Profiling, Logging, Metrics, and Crons
- Phase 3 (Guide): framework-branched installation and initialization — plain
PHP uses \Sentry\init(), Laravel uses artisan sentry:publish + Integration::handles(),
Symfony uses YAML bundle config
- Phase 4 (Cross-Link): detects companion frontend (React, Svelte, Vue) and
suggests the matching frontend SDK skill
Key design decisions:
- No wizard CLI (php/laravel/symfony not supported by @sentry/wizard)
- Laravel artisan sentry:publish --dsn= documented as the closest equivalent
- Profiling clearly marked as requiring the excimer PECL extension (Linux/macOS only)
- Metrics marked as beta using the TraceMetrics API
- Framework-specific deep dives deferred to references/laravel.md and references/symfony.md
Creates the references/ directory (populated in subsequent commits).
Co-Authored-By: Claude Sonnet 4.5 (Anthropic)
* feat(php-sdk): add profiling, logging, metrics, and crons reference files
Add four reference files to skills/sentry-php-sdk/references/ covering the
full set of PHP SDK observability features:
- profiling.md: Excimer extension prerequisites, version requirements per
framework (PHP ≥3.15, Laravel ≥3.3, Symfony ≥4.7), profiles_sample_rate
semantics (relative to traces_sample_rate), FastCGI latency mitigation,
and Relay proxy setup
- logging.md: Structured Sentry Logs feature (enable_logs: true), direct
logger API (\Sentry\logger()), Monolog bridge, Laravel sentry_logs channel
setup via .env and config/logging.php, Symfony LogsHandler + monolog.yaml
wiring, before_send_log filtering (closure for PHP/Laravel, service ID for
Symfony), auto-added attributes table, flush semantics per runtime context
- metrics.md: TraceMetrics API (count/distribution/gauge), deprecation notice
for old \Sentry\metrics() API, unit enum reference, ring buffer flush
behavior (cap 1000), before_send_metric filtering, auto-added attributes,
Symfony YAML configuration
- crons.md: withMonitor() wrapper, manual captureCheckIn() pattern, heartbeat
pattern, programmatic MonitorConfig upsert (crontab + interval schedules),
Laravel sentryMonitor() macro with full parameter reference, Symfony direct
SDK usage (no framework-specific integration), CheckInStatus/MonitorSchedule
references, rate limits (6/min per monitor-environment), alerts setup
All files follow the structure established by the sentry-python-sdk references.
Co-Authored-By: Claude Sonnet 4.6 (Anthropic)
* feat(php-sdk): add Laravel and Symfony framework reference deep-dives
Adds two comprehensive framework-specific reference files for the sentry-php-sdk skill:
- references/laravel.md (~496 lines): Full deep dive covering installation (Laravel 11+ vs 10 exception handler patterns), all config/sentry.php options including breadcrumb and tracing sub-arrays with ENV variable names, auto-instrumented operations table (11+ operations), filesystem disk opt-in instrumentation, auto-registered middleware, both log channel drivers (sentry vs sentry_logs), full queue distributed tracing with payload keys, sentryMonitor() macro with all parameters, Artisan commands, closures-and-config-cache gotcha with static callable workaround, Lumen support, Laravel Octane scope isolation warning, and Pennant feature flags integration.
- references/symfony.md (~531 lines): Full deep dive covering Flex auto-registration vs manual bundle setup, complete sentry.yaml schema with all top-level/options/messenger/tracing sub-nodes, Symfony-specific defaults (kernel.environment, PrettyVersions release, in_app_exclude auto-includes), bundle-level options table, DIC callable pattern with full service factory example (critical Symfony gotcha — YAML can't hold closures), auto-instrumented operations table (Doctrine DBAL, Twig, Cache, HTTP Client), structured logs via LogsHandler Monolog service, traditional Monolog handler with buffer support, Messenger integration (error-capture only, no tracing spans), cron monitoring using base PHP SDK functions, console command tracing config, all auto-registered event listeners, and automatic distributed tracing header handling.
These are loaded conditionally by the main SKILL.md when Laravel or Symfony is detected in the project's composer.json.
Co-Authored-By: Claude claude.ai/code
* docs(sentry-php-sdk): add error monitoring and tracing reference files
Add two comprehensive reference documents for the PHP SDK skill:
- references/error-monitoring.md — covers all capture APIs (captureException,
captureMessage, captureEvent, captureLastError), Hub/Scope management
(configureScope, withScope, withContext, push/pop), context enrichment (tags,
UserDataBag, Breadcrumb TYPE_* and LEVEL_* constants, setContext), before_send
and before_breadcrumb hooks with exact callback signatures, EventHint and
ExceptionMechanism for handled/unhandled distinction, exception chaining,
fingerprinting via Scope and before_send, and framework-specific integration
notes for plain PHP, Laravel, and Symfony. Includes a 5-row troubleshooting
table.
- references/tracing.md — covers traces_sample_rate / traces_sampler config
(including Symfony service-factory pattern for closures), the full custom
span API (TransactionContext, SpanContext, startChild, Sentry\trace() helper,
safe manual pattern), auto-instrumentation matrix for Laravel (15+ operations)
and Symfony (12+ operations), distributed tracing with sentry-trace + baggage
headers (Guzzle middleware, continueTrace(), queue worker pattern), HTML meta
tag injection for frontend/backend stitching, profiling with Excimer extension,
a span ops cheat-sheet table, and an 8-row troubleshooting table.
Both files mirror the structure of the sentry-python-sdk reference files
(config table → code examples → best practices / framework notes → troubleshooting).
Co-Authored-By: claude-sonnet-4-5 <claude-sonnet-4-5@anthropic.com>
* docs(php-sdk): register sentry-php-sdk in router, skill tree, and README
Add sentry-php-sdk to all skill registry locations:
- sentry-sdk-setup/SKILL.md: add PHP row to routing table and detection
instruction for composer.json with laravel/framework or symfony/framework-bundle
- SKILL_TREE.md: regenerated via build-skill-tree.sh with PHP entry
- AGENTS.md: add sentry-php-sdk to SDK Skills table
- README.md: add PHP (Laravel, Symfony) to SDK skills listing
- Remove stale .gitkeep from references/ (replaced by actual reference files)
Co-Authored-By: Claude Sonnet 4.5 (Anthropic)
* fix(php-sdk): address review findings — remove fabricated APIs, fix routing
Three P1 bugs and five P2 issues resolved:
P1 — Router step numbering: The PHP detection rule was numbered 6 but
appeared before the fallback step 5, creating sequence 1,2,3,4,6,5.
Corrected to 1,2,3,4,5,6 so LLMs process rules in the right priority order.
P1 — Fabricated \Sentry\withContext() API: This function does not exist
in sentry-php 4.x. Removed from the scope API table, code example, plain
PHP notes, and Octane troubleshooting row. Replaced with the correct
pushScope()/popScope() pattern throughout error-monitoring.md.
P1 — continueTrace() return value discarded: The 'Extracting incoming
trace context' example called continueTrace() without capturing its
TransactionContext return value, then created a fresh context — meaning
the transaction would never be linked to the upstream trace. Fixed to
assign the return value and use it directly, matching the correct pattern
already shown in the queue consumer example.
P2 — error_types default inconsistent: error-monitoring.md said E_ALL;
SKILL.md and the SDK research both say null/error_reporting(). Updated
the reference to error_reporting() for consistency with the SDK source.
P2 — Phantom 'never' value for max_request_body_size: Removed the
undocumented 'never' option. Valid values are none/small/medium/always.
P2 — Package name sentry/sentry-php vs sentry/sentry: All reference file
headers used sentry/sentry-php (the GitHub repo name) instead of
sentry/sentry (the Packagist package). Fixed across crons.md,
error-monitoring.md, logging.md, metrics.md, profiling.md, and tracing.md.
P2 — Tracing header mixed profiling version noise: Simplified the
tracing.md header to just SDK minimums; profiling version details already
live in profiling.md where they belong.
Co-Authored-By: Claude Sonnet 4.5 (Anthropic)
* chore: remove review artifacts from tracked files
---------
Co-authored-by: claude-sonnet-4-5 <claude-sonnet-4-5@anthropic.com>
* feat(node-sdk): add sentry-node-sdk main SKILL.md wizard
Introduces the sentry-node-sdk skill covering all three JS server-side
runtimes in a single unified wizard: Node.js, Bun, and Deno.
Key design decisions:
- One skill for all three runtimes — Bun is a thin wrapper over @sentry/node
(shares 99% of the API), and Deno shares the same core Sentry primitives,
so a unified skill with runtime-specific sections is cleaner than three
separate skills.
- Node.js wizard path: 'npx @sentry/wizard@latest -i node' is offered as
the recommended first option; manual setup covers CJS (require + first
line) and ESM (--import ./instrument.mjs flag, Node 18.19.0+ required).
- Bun: 'bun --preload ./instrument.ts' pattern; profiling explicitly marked
as unsupported (native addon incompatible).
- Deno: npm: specifier only (deno.land/x/sentry is deprecated); Deno 2.0+
required; --allow-net permissions documented; denoCronIntegration noted.
- All six framework error handlers documented (Express, Fastify, Koa, Hapi,
Connect, NestJS) with placement rules and async flag for Hapi.
- Feature support matrix per runtime so agents don't suggest profiling on Bun/Deno.
- Four-phase structure (Detect → Recommend → Guide → Cross-Link) consistent
with every other SDK skill in the bundle.
Also:
- Registers sentry-node-sdk in the sentry-sdk-setup router table
- Updates routing instructions (Next.js preference over node-sdk)
- Regenerates SKILL_TREE.md via build-skill-tree.sh (0 errors)
Co-Authored-By: Claude Sonnet 4.5 (Anthropic AI assistant)
* feat(node-sdk): add error monitoring reference for sentry-node-sdk
Adds a comprehensive ~1200-line error monitoring reference covering:
- Instrument-first rule with CJS and ESM startup patterns
- Auto-captured vs manual errors — the 'swallowed catch' gotcha
- Framework error handler placement rules (critical: differs per framework)
- Express: setupExpressErrorHandler AFTER routes
- Fastify: setupFastifyErrorHandler BEFORE routes
- Koa: setupKoaErrorHandler as FIRST middleware
- Hapi: await setupHapiErrorHandler (async — must await!)
- Connect: setupConnectErrorHandler BEFORE routes
- NestJS: SentryGlobalFilter + SentryModule.forRoot()
- Full captureException/captureMessage API with TypeScript signatures
- Scope management (v8+ Hub removal): global, isolation, current scopes
- withScope vs withIsolationScope — when to use each
- Context enrichment: setTag, setContext, setUser, setExtra, addBreadcrumb
- beforeSend, beforeBreadcrumb, ignoreErrors filtering
- Fingerprinting: per-capture, withScope, beforeSend global rules
- Event processors vs beforeSend (unlimited vs one-only)
- requestDataIntegration PII opt-in (body/cookies/IP)
- Error chains via linkedErrorsIntegration (Error.cause)
- Lifecycle: flush/close before shutdown (critical for serverless)
- Bun runtime: --preload pattern, profiling incompatibility
- Deno runtime: npm: specifier, Deno 2+ requirements
- Quick reference card
Co-Authored-By: Claude Sonnet 4.5 (Anthropic)
* feat(node-sdk): add tracing reference for sentry-node-sdk
Adds a comprehensive 816-line tracing reference covering:
- OTel-native architecture in v8+: SentrySpanProcessor, SentryPropagator,
SentrySampler, SentryContextManager and how they compose
- Full auto-instrumentation table (28+ packages) across HTTP, databases
(pg, mysql2, mongodb, redis, prisma, sequelize, typeorm, knex), message
queues (kafkajs, amqplib, pubsub, SNS/SQS, bull, bullmq), GraphQL, and
AI/LLM libraries (OpenAI, Anthropic, LangChain, Vercel AI, Google GenAI)
- Custom span APIs: startSpan (auto-end), startSpanManual (manual end),
startInactiveSpan (not active), withActiveSpan (temporarily activate)
with real-world usage examples including middleware and parallel ops
- Sampling: tracesSampleRate, tracesSampler with SamplingContext shape,
inheritOrSampleWith() (v9+), and precedence rules
- Distributed tracing: sentry-trace/baggage headers, tracePropagationTargets,
continueTrace(), manual propagation over Kafka/AMQP/WebSocket
- Advanced APIs: startNewTrace(), suppressTracing(), forceTransaction,
onlyIfParent, ignoreSpans, beforeSendSpan, getActiveSpan, getRootSpan
- Framework auto-instrumentation patterns for Express, Fastify, Koa,
Hapi, and NestJS (with @SentryTraced decorator)
- Runtime differences table: Node.js (full), Bun (via Node, no profiling),
Deno (limited auto-instrumentation, manual HTTP wrapping required)
- Troubleshooting table for 12 common issues
Co-Authored-By: Claude claude.ai/code
* docs(sentry-node-sdk): add profiling.md reference
Add comprehensive profiling reference for the sentry-node-sdk skill covering
the @sentry/profiling-node native addon and all its configuration options.
Key points documented:
- Node.js only: native C++ addon via V8 CpuProfiler; Bun and Deno are
explicitly NOT supported (clearly called out at top and in platform table)
- Installation with strict version-matching requirement
- Trace mode (auto-attach to spans) vs manual mode (startProfiler/stopProfiler)
- Continuous profiling for long-running processes and batch jobs
- V2 chunk-based architecture: 60-second upload windows, no 30s cap
- profileSessionSampleRate semantics (once per process startup, not per request)
- Supported platforms table: macOS/Linux/Windows, x64/ARM64, Node 18-24
- Environment variables: SENTRY_PROFILER_BINARY_PATH, SENTRY_PROFILER_LOGGING_MODE
- Production recommendations with performance impact notes
- Alpine/Docker setup (musl libc variant, rebuild steps)
- 10-entry troubleshooting table covering all common failure modes
Follows the pattern established by skills/sentry-nextjs-sdk/references/profiling.md
but scoped to Node.js only (no browser profiling section).
Co-Authored-By: claude-sonnet-4-5 (Anthropic)
* docs(sentry-node-sdk): add logging, metrics, and crons reference files
Three new reference files for the sentry-node-sdk skill:
- logging.md: Covers the GA Sentry.logger.* API (v9.41.0+), the fmt tagged
template literal for parameterized messages, scope-based attributes
(v10.32.0+), consoleLoggingIntegration, createConsolaReporter, the
beforeSendLog hook, manual Winston/Pino bridge patterns (no official
transports), trace linking, buffer flushing, and a troubleshooting table.
- metrics.md: Covers the Open Beta Sentry.metrics.* API (v10.25.0+) with the
three methods count/gauge/distribution (no increment or set in v10), unit
strings, attribute cardinality guidance, scope-based attributes (v10.33.0+),
beforeSendMetric hook, and flush semantics.
- crons.md: Covers the GA crons API (v7.51.1+) including captureCheckIn,
withMonitor, heartbeat vs start/finish patterns, MonitorConfig upsert,
crontab and interval schedule types, official instrumentNodeCron /
instrumentCron / instrumentNodeSchedule helpers, manual patterns for Agenda
and BullMQ, serverless flush requirement, and rate limit details.
Co-Authored-By: Claude Sonnet 4.5 (Anthropic)
* docs: register sentry-node-sdk in AGENTS.md and README.md
Add sentry-node-sdk to the SDK Skills table in both AGENTS.md and README.md.
The skill was already registered in sentry-sdk-setup router and SKILL_TREE.md
from prior work; this completes the documentation surface.
Co-Authored-By: Claude Sonnet 4.6 (Anthropic)
* fix(node-sdk): address review findings — handler placement, NestJS imports, troubleshooting
P0: Fix Fastify error handler placement in SKILL.md (BEFORE routes, not after)
P0: Fix Connect error handler placement in SKILL.md (BEFORE routes, not after)
P1: Remove erroneous await on setupFastifyErrorHandler in tracing.md
P1: Fix SentryGlobalFilter import path to @sentry/nestjs/setup in SKILL.md
P1: Add missing Troubleshooting section to error-monitoring.md (11 entries)
P2: Add Deno denoCronIntegration section to crons.md reference
Co-Authored-By: Claude Sonnet 4 (Anthropic)
* refactor(node-sdk): defer NestJS/Next.js to their dedicated skills
Replace inline NestJS setup code in SKILL.md, error-monitoring.md, and
tracing.md with cross-references to sentry-nestjs-sdk. NestJS uses a
separate package (@sentry/nestjs) with NestJS-native decorators, filters,
and GraphQL support — the dedicated skill covers it better.
Update the SDK router to:
- Add NestJS routing priority (rule 3: prefer sentry-nestjs-sdk)
- Remove NestJS from sentry-node-sdk framework list
- Clarify sentry-node-sdk is the fallback for generic Node/Bun/Deno
Update Phase 4 cross-link table to prominently surface both
sentry-nestjs-sdk and sentry-nextjs-sdk as preferred alternatives
when those frameworks are detected.
Co-Authored-By: Claude Sonnet 4 (Anthropic)
* chore: remove review files
Remove .pi/review.md and review.md that were accidentally included in the PR.
Add sentry-android-sdk to all discovery surfaces so the new skill is
reachable through every entry point:
- skills/sentry-sdk-setup/SKILL.md: add Android row to the routing table
(alphabetically between the implicit position before Cocoa) and a
dedicated routing instruction — 'If Android (build.gradle with android
plugin) is detected, use sentry-android-sdk'
- README.md: add sentry-android-sdk to the SDK Setup Wizards table
- AGENTS.md: add sentry-android-sdk to the SDK Skills table
- SKILL_TREE.md: regenerated via scripts/build-skill-tree.sh — 20 skills
scanned, 3 routers, 0 errors
Co-Authored-By: Claude claude.ai/code
Add four deep-dive reference files to the sentry-android-sdk skill bundle:
- logging.md: Structured Logs API (Sentry.logger(), SentryLogParameters, SentryAttributes),
six log levels with OTel severity numbers, Timber bridge integration, Logcat Gradle plugin
auto-instrumentation, beforeSend filtering, auto-attached attributes (user fields note for
8.33.0 PII change), batch processing constants, and a 9-entry troubleshooting table.
- metrics.md: ⚠️ Open Beta — Counter/Distribution/Gauge APIs (no Set type — prominently noted),
MetricsUnit constants reference (custom strings are not supported), SentryMetricsParameters
with custom timestamps and attributes, AndroidMetricsBatchProcessor background-flush behavior,
batch processing constants (5s delay, 10k queue cap), and a 7-entry troubleshooting table.
- crons.md: Four implementation patterns — CheckInUtils.withCheckIn (experimental wrapper),
manual two-step IN_PROGRESS/OK|ERROR lifecycle, heartbeat-only pattern, and WorkManager
wiring (no SDK adapter exists — fully manual). Prominent warning that duration is in seconds
not milliseconds. MonitorSchedule crontab + interval types, MonitorConfig options, global
Cron defaults via SentryOptions.Cron, and an 8-entry limitations/troubleshooting table.
- session-replay.md: API 26+ hard requirement prominently noted with code reference. Both
PIXEL_COPY (stable) and CANVAS (experimental, ignores all masking) screenshot strategies.
Complete SentryReplayOptions reference table. All masking mechanisms: class-based
addMaskViewClass/addUnmaskViewClass, XML sentry_privacy tags, Kotlin View extensions,
and Compose Modifier.sentryReplayMask()/sentryReplayUnmask() — with Compose 1.8+
compatibility note for SDK ≥ 8.33.0. Session lifecycle diagram, network capture config,
debug masking overlay, and a 9-entry troubleshooting table.
All files verified against io.sentry:sentry-android:8.33.0 source and docs.
Co-Authored-By: Claude claude.ai/code
Add three deep-dive reference documents to skills/sentry-android-sdk/references/,
following the same structure as the React Native SDK reference docs:
- error-monitoring.md (26 KB): covers captureException/captureMessage/captureEvent,
automatic crash handling (UncaughtExceptionHandler), ANR detection (watchdog + ANRv2
via ApplicationExitInfo on API 30+), NDK/native crash capture with scope sync, full
scope management API (configureScope/withScope/pushScope), context enrichment (tags,
user, custom contexts, breadcrumbs), beforeSend/beforeBreadcrumb hooks, fingerprinting,
view hierarchy/screenshot attachments, release health, and a 14-entry troubleshooting table.
- tracing.md (28 KB): covers three-tier instrumentation architecture (Gradle plugin,
runtime integrations, manual API), Activity TTID/TTFD, Fragment lifecycle tracing,
OkHttp spans with 9 sub-spans (DNS/TLS/connect phases), SQLite/Room query spans,
Jetpack Compose navigation, File I/O spans, user interaction tracing, slow/frozen
frames, zero-source-change Gradle plugin config, custom spans (startTransaction,
startChild, coroutines with SentryContext), distributed tracing (sentry-trace,
baggage, W3C traceparent), dynamic sampling, and a 14-entry troubleshooting table.
- profiling.md (14 KB): covers continuous/UI profiling (recommended, SDK 8.7+) vs.
legacy transaction-based profiling (30 s hard cap), TRACE vs. MANUAL ProfileLifecycle,
profile chunk model (60 s rolling), the sampling relationship (profilesSampleRate is
relative to tracesSampleRate), mutual exclusivity of the two modes, performance overhead
guidance per device tier, ProGuard mapping upload, and a 13-entry troubleshooting table.
Each file mirrors the React Native reference format: minimum SDK version at top,
Configuration section, Kotlin code examples with Java equivalents, Best Practices
(embedded in context), and a Troubleshooting table. All content sourced from SDK
source analysis (sentry-java 8.33.0) and official docs.
Co-Authored-By: Claude claude-sonnet-4-5 (Anthropic)
Implements the primary wizard skill for the Sentry Android SDK
(io.sentry:sentry-android 8.33.0, Gradle plugin 6.1.0).
The skill follows the established 4-phase wizard pattern from
sentry-react-native-sdk, adapted for the Android ecosystem:
Phase 1 — Detect: bash commands to discover Gradle DSL (Groovy vs KTS),
minSdk level, Kotlin vs Java, and presence of OkHttp, Room, Compose,
Timber, Jetpack Navigation, and Apollo integrations.
Phase 2 — Recommend: opinionated feature matrix (Error Monitoring +
Tracing always; Session Replay for API 26+ user-facing apps; Profiling,
Logging, Metrics as opt-ins).
Phase 3 — Guide: two setup paths — Path A via Gradle plugin (recommended,
handles ProGuard/R8 mapping upload, source context, and bytecode
auto-instrumentation) and Path B for manual setup. Full-featured
SentryAndroid.init() quick reference in both Kotlin and Java. Reference
dispatch table for deep dives into error monitoring, tracing, profiling,
session replay, logging, metrics, crons, and user feedback.
Phase 4 — Cross-Link: detects backend (Go, Python, Ruby, Node) and iOS
counterparts, suggests matching skills, and explains tracePropagationTargets
for distributed trace context.
Key Android-specific content:
- No wizard CLI (unlike React Native) — Gradle plugin is the recommended path
- Bytecode instrumentation via InstrumentationFeature enum (DATABASE,
FILE_IO, OKHTTP, COMPOSE, LOGCAT) — zero source changes required
- Session Replay hard requirement: API 26+ (silent no-op on API 21–25)
- Continuous UI profiling (profileSessionSampleRate) vs legacy transaction
profiling (profilesSampleRate) — mutually exclusive, decision tree included
- AndroidManifest.xml meta-data config as alternative to programmatic init
- 20+ troubleshooting entries covering common ANR, NDK, replay, profiling,
ProGuard, and distributed tracing issues
Co-Authored-By: Claude Sonnet 4.5 (Anthropic)
Fixes 1 P0 and 7 P1 issues from code review:
P0: Add missing references/ai-monitoring.md — was referenced in two
dispatch tables but did not exist. Covers OpenAI, Vercel AI SDK,
Anthropic, Google GenAI, and LangChain with NestJS-specific examples.
P1 fixes:
- Remove duplicate MonitorConfig import in crons.md (would not compile)
- Fix Prisma listed as auto-enabled in tracing.md — it requires manual
prismaIntegration() setup (consistent with SKILL.md)
- Fix anthropicIntegration → anthropicAIIntegration casing in SKILL.md
- Fix profileLifecycle default from 'manual' to 'trace' in SKILL.md
- Clarify crons.md minimum version: withMonitor() is from @sentry/node
7.76.0+, not @sentry/nestjs (which started at 8.x)
Co-Authored-By: Claude Sonnet 4 (Anthropic)
Add the new NestJS SDK skill to both documentation files so it's
discoverable alongside the existing SDK skills. Listed alphabetically
between Go and Next.js with its key framework support noted:
Express, Fastify, GraphQL, Microservices, and WebSocket.
Co-Authored-By: Claude Sonnet 4 (Anthropic)
Adds skills/sentry-nestjs-sdk/references/crons.md covering all three
check-in approaches for NestJS scheduled jobs:
- @SentryCron decorator paired with @Cron from @nestjs/schedule — the
idiomatic zero-boilerplate path; documents critical decorator ordering
rule (@SentryCron must come after @Cron, i.e. closer to the method)
- Sentry.withMonitor() for manual wrapping — recommended for Bull/BullMQ
processors and other non-@nestjs/schedule contexts where
auto-instrumentation is not supported
- Sentry.captureCheckIn() for full two-step in_progress → ok/error control,
including heartbeat pattern for long-running batch jobs
Also covers MonitorConfig upsert (slug + config auto-creates monitors on
first run), full MonitorConfig field reference, and a troubleshooting table
for the most common issues (decorator order, missing config, Bull/BullMQ,
MISSED/TIMEOUT false positives).
Co-Authored-By: Claude Sonnet 4.5 (Anthropic)
Add skills/sentry-nestjs-sdk/references/metrics.md covering the three
current metric types available in @sentry/nestjs 10.25.0+:
- count() for event occurrences and request tracking
- distribution() for latency/size measurements with percentile support
- gauge() for current-state values like queue depths
NestJS-specific examples include:
- Request counting per controller route with attributes
- Order/database query response-time distributions
- Bull/BullMQ queue depth gauges via @Cron scheduler
- Payment success/failure business event counting
Documents the beforeSendMetric hook, unit string catalogue, attribute
value types (string/number/boolean), the 2 KB per-metric size limit,
and cardinality best practices. Includes a troubleshooting table.
Note: increment() and set() are old alpha API and intentionally omitted.
Co-Authored-By: Claude Sonnet 4.5 (Anthropic)
Adds skills/sentry-nestjs-sdk/references/tracing.md — a comprehensive
tracing reference document covering the full breadth of NestJS tracing
capabilities in @sentry/nestjs.
Key topics documented:
Architecture: explains the two-layer auto-tracing stack — nestIntegration()
(three OTel instrumentations) combined with SentryTracingInterceptor for
HTTP transaction naming. Clarifies the two separate entry points
(@sentry/nestjs vs @sentry/nestjs/setup) and the critical requirement that
instrument.ts must be the very first import in main.ts.
Auto-instrumented features: HTTP requests with parameterized transaction
names, NestJS lifecycle spans (middleware, guards, pipes, interceptors,
filters — all op middleware.nestjs), @OnEvent handlers via
SentryNestEventInstrumentation with forceTransaction semantics, GraphQL,
AMQP/RabbitMQ, Kafka, Redis, and all 7 database drivers.
Manual instrumentation: startSpan / startSpanManual / startInactiveSpan
with full options reference; @SentryTraced decorator (method name → span
name, op parameter); nested span patterns; accessing and modifying the
active span; beforeSendSpan for global span mutation.
Gaps and workarounds: WebSocket gateways (continueTrace + startSpan),
Bull/BullMQ jobs (manual spans in @Process()), TCP/NATS/gRPC transports
(manual), TypeORM/Sequelize (community OTel packages).
Distributed tracing: tracePropagationTargets, continueTrace() +
getTraceData() for non-HTTP channels, manual publisher/worker pattern
for queue-based distributed traces.
Sampling: tracesSampler with SamplingContext shape, inheritance of parent
decisions for distributed traces, dynamic rates by route/op.
Profiling: nodeProfilingIntegration() setup, profileSessionSampleRate
(process-level decision), trace vs manual lifecycle modes, version
pinning requirement.
Follows the established reference format used in sentry-python-sdk.
Co-Authored-By: Claude Sonnet 4.5 (Anthropic)
Add skills/sentry-nestjs-sdk/references/logging.md covering all logging
capabilities for the NestJS SDK.
Key content:
- enableLogs: true requirement (without it all Sentry.logger.* are no-ops)
- All six log levels: trace, debug, info, warn, error, fatal
- Sentry.logger.fmt tagged template for parameterized, searchable messages
- NestJS ConsoleLogger bridge via consoleLoggingIntegration({ forceConsole: true })
- Pino integration via pinoIntegration() (SDK 10.18.0+)
- Winston integration via createSentryWinstonTransport()
- beforeSendLog hook for filtering and sanitizing log records
- Automatic log-to-trace correlation (no config needed)
- Decision table and troubleshooting guide
Bunyan is explicitly called out as unsupported.
Follows the same structure as skills/sentry-python-sdk/references/logging.md,
adapted for TypeScript/NestJS idioms and SDK-specific API differences.
Co-Authored-By: Claude Sonnet 4.5 (Anthropic)
Add skills/sentry-nestjs-sdk/references/profiling.md covering the full
profiling setup for NestJS applications using @sentry/profiling-node.
The reference documents:
- Installation requirement (version must exactly match @sentry/nestjs)
- Two profiling modes: trace lifecycle (recommended) and manual
- Side-by-side mode comparison table (triggers, coverage, use cases)
- Code examples for instrument.ts integration: trace mode, manual mode,
and production fleet sampling with profileSessionSampleRate
- Technical internals: V8 CpuProfiler, ~100Hz sampling, precompiled
binaries matrix (macOS/Linux/Windows × Node 18-24)
- Environment variables: SENTRY_PROFILER_BINARY_PATH/DIR and
SENTRY_PROFILER_LOGGING_MODE (eager vs lazy)
- Performance overhead guidance and production sampling strategy
- Troubleshooting table for common issues (binary load failures,
version mismatches, high idle CPU, missing profiles)
Co-Authored-By: Claude Sonnet 4.5 (Anthropic)
Add a new workflow skill that guides users through upgrading the Sentry
JavaScript SDK across major versions (v7→v8, v8→v9, v9→v10). Uses a
4-phase wizard flow (Detect → Recommend → Guide → Cross-Link) with
version-specific reference files distilled from official migration docs.
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
When an agent matches a skill via a router but doesn't have it installed
locally, the router now instructs it to fetch the SKILL.md directly from
the GitHub repo using the raw content URL pattern:
https://raw.githubusercontent.com/getsentry/sentry-for-ai/main/skills/<name>/SKILL.md
This ensures agents that only have the three router skills installed can
still access the full library of SDK, workflow, and feature skills
on-demand without requiring a full local clone. The Skill Tree is
referenced as the source of truth for valid skill names and paths.
Updated all three routers:
- sentry-sdk-setup (SDK setup wizard routing)
- sentry-workflow (issue fixing, code review routing)
- sentry-feature-setup (AI monitoring, OTel, alerts routing)
Co-Authored-By: Claude (Anthropic)
* fix(skills): mark wizard as user-run-only, add manual setup fallback
The Sentry wizard CLI requires interactive browser-based login and
org/project selection prompts that AI agents cannot handle. Updated all
SDK skills that reference the wizard to present it inside a blockquote
telling the user to run the command themselves in their terminal.
If the user skips the wizard, the agent proceeds with full manual setup.
Updated skills:
- sentry-nextjs-sdk
- sentry-svelte-sdk
- sentry-react-native-sdk
- sentry-dotnet-sdk
- sentry-cocoa-sdk
- sentry-sdk-skill-creator (template + philosophy reference)
Co-Authored-By: Claude (Anthropic Claude Sonnet 4)
* fix(skills): address reviewer findings for wizard guidance
- react-features.md: add interactive-login warning to source maps wizard
reference (P1 — agent would hang on browser auth)
- cocoa SKILL.md: align 'once it finishes' copy with other skills to
point to Verification instead of vague 'continue with configuration'
Co-Authored-By: Claude (Anthropic Claude Sonnet 4)
Extract validate-skill-tree from the warden workflow into a dedicated
.github/workflows/validate-skill-tree.yml. Keeps concerns separate —
warden handles AI code review, skill tree validation handles structural
integrity. Both trigger on the same PR events but run independently.
Use ${ARRAY[@]+"${ARRAY[@]}"} pattern for all array expansions that
could be empty (category arrays, errors array, function parameters).
Bash 3.2 with set -u treats "${EMPTY[@]}" as an unbound variable error,
while bash 4+ handles it gracefully. The +"..." syntax expands to nothing
when the array is unset/empty, avoiding the crash.
Also fix AGENTS.md claiming CI only runs on skills/** changes — the
validate-skill-tree job runs on all PRs (it's fast enough not to need
path filtering).
Adds a parallel CI job that runs `./scripts/build-skill-tree.sh --check`
on every PR. The job checks out the repo with minimal permissions
(contents: read) and fails if SKILL_TREE.md is stale or any skill
frontmatter/breadcrumb/router-table validation errors are found.
Running it as a separate job (rather than a step in the warden review
job) keeps concerns isolated and lets both jobs run in parallel.
Co-Authored-By: Claude Sonnet 4.5 (Anthropic)
Documents the router pattern that keeps agent startup metadata lean
(~300 tokens vs ~1,600+ as the skill library grows). Covers:
- How the three router skills (sentry-sdk-setup, sentry-workflow,
sentry-feature-setup) gate access to hidden child skills via
disable-model-invocation
- Category taxonomy with responsible routers
- Step-by-step checklist for adding a new skill (frontmatter fields,
breadcrumb, router table update, build script)
- Guidance on splitting categories once they exceed ~10 skills
- Reference to scripts/build-skill-tree.sh for local validation and
its --check flag used in CI
This gives contributors (human and AI) a single authoritative source
for skill tree conventions without needing to reverse-engineer the
frontmatter or ask questions.
Co-Authored-By: Claude Sonnet 4.6 (Anthropic)
Adds scripts/build-skill-tree.sh — a bash-only script that scans
all skills/*/SKILL.md files, regenerates SKILL_TREE.md from live
frontmatter data, and validates the entire skill hierarchy.
What the script does:
1. Scan — finds all SKILL.md files via find, parses YAML frontmatter
(name, description, category, parent, role, disable-model-invocation)
using awk. No external dependencies beyond standard Unix tools.
2. Categorize — groups skills by category field, identifies routers
by role: router.
3. Generate — rebuilds SKILL_TREE.md with Quick Navigation table,
per-category skill tables (SDK Setup, Workflow, Feature Setup,
Internal), and short column values extracted from descriptions.
4. Validate — checks every rule without stopping on first failure:
- Non-router/non-internal skills must have category, parent, and
disable-model-invocation: true
- Internal skills must have disable-model-invocation: true
- Every skill's parent must exist and have role: router
- Each skill must appear in its router's SKILL.md
- All breadcrumb .md links must resolve to real files
- Warns on unknown categories
5. Stale check — diffs generated vs existing SKILL_TREE.md; writes
file unless --check is passed (check-only mode for CI).
Uses a temp-directory pattern for per-skill data storage instead of
bash 4 associative arrays, keeping it compatible with macOS bash 3.2.
Also updates SKILL_TREE.md to match the script's generated output
(column values are now extracted from descriptions via sed, ordering
follows find | sort alphabetical).
Co-Authored-By: Claude Sonnet 4.5 (Anthropic)
Creates a flat sitemap at the repo root that gives any agent an instant
overview of the full skill structure. The file contains:
- Quick navigation table mapping user intent to the three router skills
(sentry-sdk-setup, sentry-workflow, sentry-feature-setup)
- Four categorized tables covering all 16 skills: SDK Setup (9 platforms),
Workflow (3 skills), Feature Setup (3 skills), and Internal (1 skill)
- Every skill name and path is a clickable markdown link
- Kept under 1000 tokens as specified
This file serves as the entry point agents use to locate the right skill
before diving into individual SKILL.md files. It will later be generated
automatically by the build script; this is the hand-authored initial version.
Co-Authored-By: Claude Sonnet 4.6 (Anthropic)
Extends the skill-tree navigation pattern (already applied to SDK skills)
to the remaining workflow, feature-setup, and internal skills.
Each file receives three new frontmatter fields:
- category: workflow | feature-setup | internal
- parent: router skill name (omitted for internal/sentry-sdk-skill-creator)
- disable-model-invocation: true
And a breadcrumb blockquote immediately after the closing --- for
contextual navigation:
Workflow skills (parent: sentry-workflow):
sentry-code-review, sentry-pr-code-review, sentry-fix-issues
Feature-setup skills (parent: sentry-feature-setup):
sentry-setup-ai-monitoring, sentry-otel-exporter-setup, sentry-create-alert
Internal skills (no parent router):
sentry-sdk-skill-creator → breadcrumb links to SKILL_TREE.md only
No existing skill content was modified — pure additive changes.
Co-Authored-By: Claude Sonnet 4.5 (Anthropic)
Add category, parent, and disable-model-invocation fields to the YAML
frontmatter of all 9 SDK skill files, and insert a breadcrumb navigation
line as the first body element after the closing ---.
Each skill now declares:
category: sdk-setup
parent: sentry-sdk-setup
disable-model-invocation: true
And opens with a breadcrumb blockquote:
> [All Skills](../../SKILL_TREE.md) > [SDK Setup](../sentry-sdk-setup/SKILL.md) > <Platform> SDK
This establishes the skill tree hierarchy for the sdk-setup category,
enabling routers and tooling to discover parent/child relationships and
preventing these implementation skills from being invoked directly by
the model without going through the sentry-sdk-setup router.
No existing skill content was modified — only additive changes.
Co-Authored-By: Claude Sonnet 4.5 (Anthropic)
Introduce three new router-role skills that act as entry points for common
Sentry tasks, routing agents to the appropriate specialized skill based on
user intent and detected platform context.
- sentry-sdk-setup: detects project platform from files (package.json,
go.mod, Gemfile, *.xcodeproj, etc.) and maps to one of 9 SDK skills
(Cocoa, .NET, Go, Next.js, Python, React Native, React, Ruby, Svelte).
Includes priority rules for Next.js over React and React Native over React,
with a fallback to docs.sentry.io/platforms/ for unmatched platforms.
- sentry-workflow: routes debugging and code review tasks to sentry-fix-issues
(MCP-based production debugging), sentry-code-review (sentry[bot] PR
comments), or sentry-pr-code-review (Seer Bug Prediction reviews).
- sentry-feature-setup: routes feature configuration requests to
sentry-setup-ai-monitoring (LLM/AI SDK instrumentation),
sentry-otel-exporter-setup (OTel Collector pipelines), or
sentry-create-alert (workflow engine alerts and notifications).
All three skills use role: router in frontmatter and include breadcrumb
navigation back to SKILL_TREE.md.
Co-Authored-By: Claude Sonnet 4.5 (Anthropic AI assistant)
Restructure the README around what users can actually do with the
plugin rather than listing technical components. Opens with the core
value prop — your AI assistant knows code, this teaches it Sentry — then
shows real examples for each use case before diving into skill tables.
Drops the plugin structure tree (internal detail) and streamlines
installation instructions. Adds a contributing section pointing to the
agent skills spec and the sdk-skill-creator skill.
Co-Authored-By: Claude (Anthropic)
Update documentation to reflect the full skill catalog ported from
sentry-agent-skills. Skills are now organized into four categories:
- SDK bundles (9): full platform setup wizards with reference docs
- Setup skills (2): AI monitoring, OTel exporter
- Workflow skills (4): code review, PR review, fix issues, create alerts
- Authoring skills (1): SDK skill creator
Also adds scripts/generate-skill-list.sh from sentry-agent-skills for
generating skill lists from SKILL.md frontmatter.
Co-Authored-By: Claude (Anthropic)
Cursor Agent