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)
Daniel Griesser