ref(skills): promote skills-next to root by evanpurkhiser · Pull Request #269 · getsentry/sentry-for-ai

evanpurkhiser · 2026-07-09T19:51:30Z

Promotes the staged skills-next/ content into its canonical location and introduces the flat "standalone" skill shape alongside the existing router/leaf skills.

Moves

skills-next/skills/* → skills/ — the new flat orchestrator skills: sentry-get-started, sentry-instrument, sentry-debug-issue.
skills-next/references/ → references/ (repo root) — the shared reference library, where the plugin hydrate step (hydrate-references.py --references references) and the skills.sentry.dev proxy's references fallback already expect it.

Validator (build-skill-tree.sh)

Standalone skills (no role, no category) — flat, self-contained; validated only for name + description, surfaced in a new Standalone Skills section at the top of SKILL_TREE.md. Their shared references are hydrated in at build time from references.yml, so the breadcrumb/sibling-link check is skipped for them.
Router / leaf skills — validated and rendered as before, kept for the workflow and feature skills still to be migrated.
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/ in ref(skills): move superseded skills to skills-legacy #265.

SKILL_TREE.md sections are now: Standalone Skills → Workflows → Feature Setup.

Independent of #265 (disjoint file sets). On this PR's base the per-SDK skills still exist in skills/ (they validate but no longer render); once #265 lands they're gone. Whichever of #265/#269 merges second needs a SKILL_TREE.md regen — CI's --check flags it.

Follow-ups (not here): reconcile AGENTS.md's "Skill Tree Navigation" section and the .github/agents/skill-creator|skill-updater docs for the standalone shape.

evanpurkhiser · 2026-07-09T19:52:06Z

-# validates the skill hierarchy, and checks breadcrumb links.
+# Scans all skills/*/SKILL.md files and regenerates SKILL_TREE.md as a
+# flat index (one row per skill: name + description). Skills are flat and
+# self-contained — there is no router/leaf hierarchy, category, or parent.


no need to mention this. it's a historical detail

sentry · 2026-07-09T20:07:06Z

+    # ── (f) Breadcrumb links resolve (router/leaf skills only) ──
+    # Standalone skills link shared references (references/…) that are copied
+    # in by the build's hydrate step, so they don't exist beside the raw
+    # source; skip the sibling-link check for them.
+    if [[ "$role" != "router" && -z "$cat" ]]; then
+      continue
+    fi
+
    local skill_dir
    skill_dir="$(dirname "$skill_file")"



Bug: The build process references search-query-language.md, which is missing. The build script warns but doesn't fail, leading to a skill with a broken documentation link at runtime.
_{Severity: MEDIUM}

Suggested Fix

Add the missing search-query-language.md file to the references/ directory. Alternatively, if the reference is no longer needed, remove it from skills/sentry-debug-issue/references.yml and any markdown files that link to it.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not valid. Location: scripts/build-skill-tree.sh#L346-L359 Potential issue: The `sentry-debug-issue` skill declares a dependency on `search-query-language.md` in its `references.yml`. However, this file does not exist in the repository. The `hydrate-references.py` script, which is part of the build process, will encounter this missing file, print a warning to stderr, but will not exit with an error. As a result, the skill will be built and deployed with a broken reference. When an agent loads the `sentry-debug-issue` skill and attempts to access this documentation, it will encounter a broken link, leading to missing context during its operation.

Also affects:

skills/sentry-debug-issue/references.yml:2

skills/sentry-debug-issue/SKILL.md:13

skills/sentry-debug-issue/SKILL.md:52

references/concepts/tracing.md

references/concepts/logging.md

references/concepts/session-replay.md

references/concepts/user-feedback.md

references/concepts/monitors.md

references/concepts/releases.md

_{Did we get this right? 👍 / 👎 to inform future reviews.}

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.

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 51b5805. Configure here.}

cursor · 2026-07-09T20:50:09Z

+    # Standalone skill: flat and self-contained, no router/category. These are
+    # the next-generation skills; the router/leaf skills below are migrating
+    # toward this shape.
+    STANDALONE+=("$name")


Empty category misclassifies skills

Medium Severity

Any skill without role: router and with an empty category is now bucketed as standalone, validated only for description, and emitted in the public Standalone Skills table. Router leaves and internal skills that lose or omit category no longer fail the old required-field checks and can surface in the index incorrectly.

Additional Locations (2)

scripts/build-skill-tree.sh#L299-L305

scripts/build-skill-tree.sh#L203-L210

^{Reviewed by Cursor Bugbot for commit 51b5805. Configure here.}

evanpurkhiser requested review from HazAT and MathurAditya724 July 9, 2026 19:51

evanpurkhiser commented Jul 9, 2026

View reviewed changes

cursor Bot reviewed Jul 9, 2026

View reviewed changes

Comment thread scripts/build-skill-tree.sh

evanpurkhiser force-pushed the evanpurkhiser/ref-skills-promote-skills-next-to-root branch 2 times, most recently from 9d00702 to 716893d Compare July 9, 2026 20:04

sentry Bot reviewed Jul 9, 2026

View reviewed changes

evanpurkhiser force-pushed the evanpurkhiser/ref-skills-promote-skills-next-to-root branch from 716893d to 51b5805 Compare July 9, 2026 20:45

cursor Bot reviewed Jul 9, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

ref(skills): promote skills-next to root#269

ref(skills): promote skills-next to root#269
evanpurkhiser wants to merge 1 commit into
mainfrom
evanpurkhiser/ref-skills-promote-skills-next-to-root

evanpurkhiser commented Jul 9, 2026 •

edited

Loading

Uh oh!

evanpurkhiser Jul 9, 2026

Uh oh!

Uh oh!

sentry Bot Jul 9, 2026

Uh oh!

cursor Bot left a comment

Uh oh!

cursor Bot Jul 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Uh oh!

Conversation

evanpurkhiser commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

evanpurkhiser Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sentry Bot Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot Jul 9, 2026

Choose a reason for hiding this comment

Empty category misclassifies skills

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

evanpurkhiser commented Jul 9, 2026 •

edited

Loading