The plugins had no releases to speak of: one hand-edited version copied
across four manifests, no tags in any distribution repo, and every merge
rewriting each repo's main. Nothing separated "merged" from "shipped",
and no ref named a version anyone could pin or roll back to.
src/plugins/version.json is now the one version, stamped over the 0.0.0
placeholder in each manifest at build time, so the four plugins move in
lockstep from a single bump.
Deploys land on develop instead, leaving main to advance only when the
Release plugins workflow cuts a version -- which tags this repo
plugin/v<version> and each distribution repo v<version>. Consumers all
resolve main today, so this is what makes shipping deliberate rather
than a side effect of merging.
Develop builds carry their distance from the last tag
(1.2.1-dev.14.gdeadbee). The patch bump is load-bearing: semver ranks a
prerelease below its release, so 1.2.0-dev.14 would compare older than
the 1.2.0 it is fourteen commits ahead of, and build metadata is ignored
in comparisons entirely.
Now that the tree is formatted, this keeps it that way. prek runs the hooks the
way sentry runs its own, so one command covers Markdown formatting, file
hygiene, workflow schemas, and the two validators this repo already had.
scripts/lint.sh is the entrypoint and pins prek through uvx, so there is nothing
to install first. It replaces the Validate Skill Tree workflow, whose two steps
are hooks now.
Most hooks fix rather than report, and the workflow leans on that: on a pull
request from this repository it pushes whatever they rewrote back to the branch
instead of failing a check, then runs them again to report the state after the
fix -- a GITHUB_TOKEN push starts no workflow run of its own, so the fix commit
would otherwise carry no signal. Fork pull requests have no branch to push to
and fail with the command to run. Sentry pushes these fixes under a GitHub App
token so the follow-up commit gets checked normally; that app's private key is
not available to this repo.
Markdown belongs to flowmark alone. It writes a trailing space on the blank
lines inside a blockquote, so trailing-whitespace and end-of-file-fixer skip
Markdown rather than strip what flowmark rewrites on the next run, forever.
src/SKILL_TREE.md stays out of flowmark's reach through .flowmarkignore because
build-skill-tree.sh generates it, and skills-legacy/ is excluded repo-wide as
frozen content nothing ships.
Dissolving the last routers (#310) emptied both category buckets, but the
generator still emitted their headings, intro prose, and a bare table header
with no rows underneath. That ships to every agent that reads SKILL_TREE.md as
two sections advertising capabilities with nothing in them.
Removing just those sections would leave a worse state behind: a skill carrying
a category would still be scanned and validated, but nothing would render it, so
it would vanish from the tree with the script reporting success. So retire the
concept instead of half of it.
Nothing needs it. No skill carries category, parent, role, or
disable-model-invocation; outside this script nothing reads those fields at all.
What remained was ~120 lines validating and rendering a model the project has
abandoned -- router roles, parent-must-be-a-router, leaf-listed-in-its-router,
per-category tables -- none of it reachable. The hierarchy validation is
replaced by the rule that actually holds now: those four fields are rejected
outright, so a stale copy-paste or an attempt to reintroduce routing fails
loudly rather than dropping a skill silently.
The categorize pass collapses with it: one flat table means every skill is a
row, so ALL_SKILLS is the list and the STANDALONE/ROUTERS split has nothing left
to distinguish. The heading becomes "Available Skills" -- "Standalone" only
meant something in contrast to the category sections that are gone.
The inert breadcrumb check goes too. It skipped every skill that was neither a
router nor categorized, which is all of them, so no link has been checked for
some time; replacing it is a separate change.
Skill link checking has been silently off. build-skill-tree.sh has a
breadcrumb-link check, but it opens by skipping any skill that is neither a
router nor categorized:
if [[ "$role" != "router" && -z "$cat" ]]; then
continue
fi
Every skill is standalone now, so every skill takes that branch and no link is
checked at all. It was not turned off deliberately -- the guard was written when
standalone skills were the exception, and going flat quietly disabled it for
everything. That leaves the failure #308 fixed with nothing guarding it.
Check the built plugin trees rather than the source. A skill only becomes
self-contained once the build hydrates its declared references in, so the source
tree cannot answer the question on its own -- any check there has to
re-implement the hydrator's glob semantics and can drift from it. Building
first removes the simulation: what gets validated is the tree a user installs,
per agent, including each agent's own transform.
Every agent is built and checked, since layout and transforms differ between
them and a link can survive one while breaking another. The builds need no
network or credentials and take well under a second each, so the whole sweep
costs a few seconds per pull request.
Passing the source library in as well buys a cause instead of a symptom: a
target missing from the built skill but present in the library means the
manifest never declared it, so the error says to fix references.yml rather than
leaving a bare dangling-link report.
Runs in the existing validate job, which gains a uv install matching the one
deploy-plugins already uses.
Major-version SDK upgrades are a rare, low-frequency task and don't fit the
task-shaped skill set the getting-started redesign is converging on. Retiring
sentry-sdk-upgrade empties the sentry-workflow router (its only remaining child
after the code-review skills were removed in #283), so drop the router too.
Move sentry-sdk-upgrade under skills-legacy/ the way #265 retired the other
superseded skills: out of the plugin build and the drift automation, still
served by skills.sentry.dev for existing URL consumers. The router itself is
deleted rather than moved — a router that fronts nothing has nothing to serve.
Drop the README/AGENTS listings and the workflow entries in the AGENTS
skill-tree navigation, then regenerate SKILL_TREE.md. sentry-feature-setup is
now the last router as the library migrates toward flat standalone skills.
(cherry picked from commit ef57592f08263023198ddb43a851df02adecd544)
AI/LLM monitoring is a signal, and sentry-instrument already wires it up per
platform from the reference library. With the shared concepts/ai-monitoring.md
now in place (#285) as the canonical home for the cross-cutting rules —
gen_ai.* model, conversation-ID format, token/cost accounting, PII and sampling
strategy — the standalone skill is fully absorbed.
Remove sentry-setup-ai-monitoring: drop the skill, its entry and AI wording in
the sentry-feature-setup router, and the README/AGENTS listings, then regenerate
SKILL_TREE.md.
Fold in the parts that only lived in the skill, language-agnostically, so
nothing is lost with it: auto-instrumentation is runtime-dependent (there is
nothing to patch on workerd or in the browser), the input/output message shape
and why thinking must be a reasoning part rather than text, and the root-span
sampling rule that decides whether keeping gen_ai at 100% means matching the
gen_ai op or the HTTP route in front of it. Also drop the last pointer at the
retired skill name, in the PHP reference.
(cherry picked from commit b7d29503746a3e38dff9c4e54f01e3206bdd12b7)
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)
Evan Purkhiser