A skill ships only what its references.yml declares, so a reference doc that
links a sibling the manifest omits reads fine in this repo and dangles in every
published plugin. 46 pointers were broken in the built output — the agent is
told "see data-scrubbing.md" and finds nothing there.
Two distinct causes:
- `search-query-language.md` lives at references/ root, but six concepts/ docs
linked it as a sibling. Fixed to `../search-query-language.md`.
- The concepts/ docs cross-link each other, while the manifests hand-picked a
subset. Each of the three manifests now takes `concepts/*.md` whole. The docs
are small and hydration only puts files on disk — nothing is read until a
pointer is followed — so presence costs nothing and SKILL.md still decides
what gets read. The lean per-SDK scoping in sentry-get-started is unchanged.
- sdks/index.md linked STRUCTURE.md, which is marked internal and deliberately
never shipped. Dropped the pointer; the format contract is for maintainers,
who read it in the repo.
To keep it fixed, `check_skill_links` now runs at the end of all four plugin
builds and fails on any Markdown link that doesn't resolve in the built tree.
It runs last, against the plugin root, so breadcrumbs to ../../SKILL_TREE.md
are checked where they actually land. Verified: all four builds pass, and the
check fails as intended when a broken link is introduced.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
sentry-workflow routed to exactly one skill, sentry-sdk-upgrade, and its
description was that skill's description reworded. That is one always-loaded
description plus a file read plus a routing hop to reach one skill — strictly
more expensive than exposing the skill directly, on both context and
cognitive load.
The router layer was sized for a 30+ skill library. Eight skills ship today;
the 26 the docs still describe live in skills-legacy and are built by nothing.
- Delete the router; sentry-sdk-upgrade becomes standalone (no category,
parent, breadcrumb, or disable-model-invocation), matching the shape the
newer skills already use.
- Teach the generator to skip a category with no skills left, so an emptied
section stops rendering a header and column titles the tree can't route to.
- Drop the "Review code" option from the SKILL_TREE entry menu. The skills
behind it were removed in 7141b95, so the menu was offering a capability
that no longer exists.
- Stop restating the greet-and-ask protocol in the tree header. sentry-get-started
Step 0 owns it and does it better; two copies means the agent runs whichever
it read first.
sentry-feature-setup still fronts three skills and stays for now.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Relocate all buildable source -- skills/, references/, plugin-src/, and
SKILL_TREE.md -- under a single src/ tree so the repo root cleanly separates
source from the frozen skills-legacy/ wizards, the installer package, assets,
and docs. plugin-src/ becomes src/plugins/.
The per-agent build scripts now resolve their content root at $REPO_ROOT/src,
build-skill-tree.sh scans src/skills and writes src/SKILL_TREE.md, and the
deploy and skill-drift workflows point at the new paths. references.yml
manifests are unchanged -- their paths are relative to the references root the
build passes in.
The /seer command only wrapped what users can already do by asking the agent
natural-language questions directly against the Sentry MCP server, so it earned
its own maintenance surface (a command file, build wiring, and docs) for no real
capability. Remove the command along with the commands/ build plumbing
(copy_commands, per-agent build.sh calls, the deploy-plugins path trigger) and
every /seer reference across the READMEs, AGENTS.md, TELEMETRY.md, plugin
manifests, and concept docs.
Moves the staged next-generation content into its canonical location:
skills-next/skills/* -> skills/ (the flat, self-contained skills
sentry-get-started, sentry-instrument, sentry-debug-issue) and
skills-next/references/ -> references/ (the shared library the plugin
hydrate step and the skills.sentry.dev proxy already expect at repo root).
Teaches build-skill-tree.sh about standalone (flat) skills: they need only
a name + description and are surfaced in a new "Standalone Skills" section
at the top of SKILL_TREE.md. The SDK-setup router section (and its keyword
Quick Lookup) is dropped from the index — sentry-instrument now covers SDK
setup, and the per-SDK skills move to skills-legacy/ (#265). The router/leaf
machinery is kept for the workflow and feature skills still to be migrated.
The skill routers and the skill-tree index carried explicit curl
instructions ("Use curl to download...", "Append the path to
https://skills.sentry.dev/...") plus a redundant `Path` column beside the
relative-link column that already navigates. That guidance was duplicated
across every router and, worse, shipped inside the plugin distributions,
where the reader has the files locally and should never curl anything.
Navigation over HTTP now lives in the skills.sentry.dev proxy, which
appends a per-file note (and a usage preamble on the index) telling an
HTTP reader how to resolve the relative links it already sees. That lets
the sources stay clean: a single relative-link column that resolves both
locally (plugin) and over HTTP (mirror). This strips the curl scaffolding
from the three routers and from the SKILL_TREE.md generator, and converts
the remaining path-only lookup tables to relative links.
Task-shaped skills will draw their reference material (per-platform SDK
guides, per-signal concepts) from a single maintained library rather
than duplicating it. Each shipped skill must still be self-contained, so
the build copies a skill's declared references into it.
Add a CONTENT_ROOT env var (default: repo root) so the same build steps
can assemble an alternate skill tree, e.g. CONTENT_ROOT=skills-next.
hydrate-references.py walks a skills directory: for every skill with a
references.yml it brace-expands and globs the `needs:` patterns against
the library, copies the matches into the skill's references/ preserving
subpaths, and strips the manifest so it never ships. It runs via `uv run
--script` with inline PyYAML and braceexpand dependencies. build-common.sh
invokes it once per build, and only when some skill declares references,
so existing skills are unaffected and the common case spawns no
interpreter.
Factor the steps shared across all four agent builders into
build-common.sh (content-root resolution, skill copy+hydrate, commands,
SKILL_TREE), sourced by each plugin-src/<agent>/build.sh.
The preReleaseCommand failed in craft's container with "pnpm: command not
found" -- the image ships npm but not pnpm. Switch to `npm pkg set version`,
a plain package.json edit with no install, lockfile, or git-check side
effects.
craft's default version bump targets the repo-root package.json, which is
private and unversioned. The published package lives in packages/installer,
so its version stayed at 0.1.0 and npm rejected the 0.1.1 publish as a
duplicate. Wire a preReleaseCommand that bumps packages/installer instead.
* 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 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)
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.
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 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)
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)
Sergiy Dybskiy