feat: refactor SKILL.md into modular reference files

[BYK]

Summary

Closes #319

Split the monolithic 824-line SKILL.md into a compact index (~300 lines) with agent guidance + command summaries, and 12 per-group reference files with full flag/example details.

Changes

New Agent Guidance Document

• docs/src/content/docs/agent-guidance.md — Operational guidance for AI agents including context window tips, safety rules, workflow patterns, and common mistakes
• Loaded by the generator and injected into SKILL.md's "Agent Guidance" section

Generator Refactoring (script/generate-skill.ts)

• Produces 3 types of output:
  • SKILL.md — compact ~297-line index with agent guidance + command summaries (down from 824)
  • references/*.md — 12 per-group reference files with full flag/example details
  • index.json — skill discovery manifest for .well-known
• Route-to-reference mapping groups related commands (trace+span → traces.md, team+repo → teams.md, cli+init+schema → setup.md)
• Strips global flags from compact index (mentioned once in Global Options section)
• Cleans references/ directory before writing to handle stale files
• Each reference file has YAML frontmatter with name, version, description, requires

Checker Update (script/check-skill.ts)

• Verifies ALL generated files using Bun.Glob (SKILL.md + references/*.md + index.json)
• Detects changed, new, AND removed files

Runtime Installer Update (src/lib/agent-skills.ts)

• New fetchAllSkillFiles() fetches SKILL.md + all 12 reference files in parallel
• installAgentSkills() creates references/ directory and writes all files
• Graceful degradation: reference file failures don't block SKILL.md installation
• AgentSkillLocation type now includes referenceCount

Directory Symlinks

• .cursor/skills/sentry-cli/references → source references
• docs/public/.well-known/skills/sentry-cli/references → source references

CI Update

• check-skill job updated to git add entire skill directory + index.json

Tests

• New tests for fetchAllSkillFiles, reference file installation, graceful degradation

Metrics

• SKILL.md: 824 lines → 297 lines (64% reduction)
• Reference files: 788 total lines across 12 files
• Tests: 24 tests passing

[github-actions]

Semver Impact of This PR

🟡 Minor (new features)

📋 Changelog Preview

This is how your changes will appear in the changelog.
Entries from this PR are highlighted with a left border (blockquote style).

---

New Features ✨

• Refactor SKILL.md into modular reference files by BYK in #458

Bug Fixes 🐛

• (test) Use os.tmpdir() for test temp directories by BYK in #457
• Improve error messages — fix ContextError/ResolutionError misuse by BYK in #456

Internal Changes 🔧

• (list) Align all list commands to issue list standards by BYK in #453

---

_{🤖 This preview updates automatically when you update the PR.}

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://cli.sentry.dev/pr-preview/pr-458/
Built to branch gh-pages at 2026-03-18 12:13 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[github-actions]

Codecov Results 📊

✅ 116 passed | Total: 116 | Pass Rate: 100% | Execution Time: 0ms

📊 Comparison with Base Branch

Metric	Change
Total Tests	—
Passed Tests	—
Failed Tests	—
Skipped Tests	—

✨ No test changes detected

All tests are passing successfully.

✅ Patch coverage is 100.00%. Project has 1149 uncovered lines.
✅ Project coverage is 95.2%. Comparing base (base) to head (head).

Coverage diff

@@            Coverage Diff             @@
##          main       #PR       +/-##
==========================================
+ Coverage    95.20%    95.20%        —%
==========================================
  Files          176       176         —
  Lines        23871     23930       +59
  Branches         0         0         —
==========================================
+ Hits         22724     22781       +57
- Misses        1147      1149        +2
- Partials         0         0         —

---

Generated by Codecov Action

[cursor]

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

There are 2 total unresolved issues (including 1 from previous review).

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