feat: refactor SKILL.md into modular reference files (#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:
- Create docs/src/content/docs/agent-guidance.md with operational guidance
  for AI coding agents (context window tips, safety rules, workflow
  patterns, common mistakes)
- Refactor script/generate-skill.ts to produce SKILL.md index +
  references/*.md files + auto-generate index.json
- Update script/check-skill.ts to verify all generated files (not just
  SKILL.md)
- Update src/lib/agent-skills.ts to fetch and install SKILL.md +
  reference files (with graceful degradation)
- Add directory symlinks for .cursor/ and docs/.well-known/
- Update CI workflow to git add entire skill directory
- Update tests for new multi-file API

The SKILL.md remains the primary entry point for Claude Code and other
agents. Reference files provide full command details that agents can
read on-demand when they need specifics about a command group.

Author: BYK

.cursor/skills/sentry-cli/references

@@ -0,0 +1 @@
+../../../plugins/sentry-cli/skills/sentry-cli/references

.github/workflows/ci.yml

@@ -85,7 +85,7 @@ jobs:
           echo "Nightly version: ${VERSION}"
 
   check-skill:
-    name: Check SKILL.md
+    name: Check skill files
     needs: [changes]
     if: needs.changes.outputs.skill == 'true'
     runs-on: ubuntu-latest
@@ -112,22 +112,22 @@ jobs:
         run: bun install --frozen-lockfile
       - name: Generate API Schema
         run: bun run generate:schema
-      - name: Check SKILL.md
+      - name: Check skill files
         id: check
         run: bun run check:skill
         continue-on-error: true
-      - name: Auto-commit regenerated SKILL.md
+      - name: Auto-commit regenerated skill files
         if: steps.check.outcome == 'failure' && steps.token.outcome == 'success'
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add plugins/sentry-cli/skills/sentry-cli/SKILL.md
-          git commit -m "chore: regenerate SKILL.md"
+          git add plugins/sentry-cli/skills/sentry-cli/ docs/public/.well-known/skills/index.json
+          git commit -m "chore: regenerate skill files"
           git push
-      - name: Fail for fork PRs with stale SKILL.md
+      - name: Fail for fork PRs with stale skill files
         if: steps.check.outcome == 'failure' && steps.token.outcome != 'success'
         run: |
-          echo "::error::SKILL.md is out of date. Run 'bun run generate:skill' locally and commit the result."
+          echo "::error::Skill files are out of date. Run 'bun run generate:skill' locally and commit the result."
           exit 1
 
   lint:

AGENTS.md

@@ -3,7 +3,21 @@
     {
       "name": "sentry-cli",
       "description": "Guide for using the Sentry CLI to interact with Sentry from the command line. Use when the user asks about viewing issues, events, projects, organizations, making API calls, or authenticating with Sentry via CLI.",
-      "files": ["SKILL.md"]
+      "files": [
+        "SKILL.md",
+        "references/api.md",
+        "references/auth.md",
+        "references/dashboards.md",
+        "references/events.md",
+        "references/issues.md",
+        "references/logs.md",
+        "references/organizations.md",
+        "references/projects.md",
+        "references/setup.md",
+        "references/teams.md",
+        "references/traces.md",
+        "references/trials.md"
+      ]
     }
   ]
 }

docs/public/.well-known/skills/index.json

@@ -0,0 +1 @@
+../../../../../plugins/sentry-cli/skills/sentry-cli/references

docs/public/.well-known/skills/sentry-cli/references

@@ -0,0 +1,91 @@
+---
+title: Agent Guidance
+description: Operational guidance for AI coding agents using the Sentry CLI
+---
+
+Best practices and operational guidance for AI coding agents using the Sentry CLI.
+
+## Design Principles
+
+The `sentry` CLI follows conventions from well-known tools — if you're familiar with them, that knowledge transfers directly:
+
+- **`gh` (GitHub CLI) conventions**: The `sentry` CLI uses the same `<noun> <verb>` command pattern (e.g., `sentry issue list`, `sentry org view`). Flags follow `gh` conventions: `--json` for machine-readable output, `--fields` to select specific fields, `-w`/`--web` to open in browser, `-q`/`--query` for filtering, `-n`/`--limit` for result count.
+- **`sentry api` mimics `curl`**: The `sentry api` command provides direct API access with a `curl`-like interface — `--method` for HTTP method, `--data` for request body, `--header` for custom headers. It handles authentication automatically. If you know how to call a REST API with `curl`, the same patterns apply.
+
+## Context Window Tips
+
+- Use `--fields id,title,status` on list commands to reduce output size
+- Use `--json` when piping output between commands or processing programmatically
+- Use `--limit` to cap the number of results (default is usually 10–100)
+- Prefer `sentry issue view PROJECT-123` over listing and filtering manually
+- Use `sentry api` for endpoints not covered by dedicated commands
+
+## Safety Rules
+
+- Always confirm with the user before running destructive commands: `project delete`, `trial start`
+- Verify the org/project context is correct before mutations — use `sentry auth status` to check defaults
+- Never store or log authentication tokens — use `sentry auth login` and let the CLI manage credentials
+- When in doubt about the target org/project, use explicit `<org>/<project>` arguments instead of auto-detection
+
+## Workflow Patterns
+
+### Investigate an Issue
+
+```bash
+# 1. Find the issue
+sentry issue list my-org/my-project --query "is:unresolved" --limit 5
+
+# 2. Get details
+sentry issue view PROJECT-123
+
+# 3. Get AI root cause analysis
+sentry issue explain PROJECT-123
+
+# 4. Get a fix plan
+sentry issue plan PROJECT-123
+```
+
+### Explore Traces and Performance
+
+```bash
+# 1. List recent traces
+sentry trace list my-org/my-project --limit 5
+
+# 2. View a specific trace with span tree
+sentry trace view my-org/my-project/abc123def456...
+
+# 3. View spans for a trace
+sentry span list my-org/my-project/abc123def456...
+
+# 4. View logs associated with a trace
+sentry trace logs my-org/abc123def456...
+```
+
+### Stream Logs
+
+```bash
+# Stream logs in real-time
+sentry log list my-org/my-project --follow
+
+# Filter logs by severity
+sentry log list my-org/my-project --query "severity:error"
+```
+
+### Arbitrary API Access
+
+```bash
+# GET request (default)
+sentry api /api/0/organizations/my-org/
+
+# POST request with data
+sentry api /api/0/organizations/my-org/projects/ --method POST --data '{"name":"new-project","platform":"python"}'
+```
+
+## Common Mistakes
+
+- **Wrong issue ID format**: Use `PROJECT-123` (short ID), not the numeric ID `123456789`. The short ID includes the project prefix.
+- **Forgetting authentication**: Run `sentry auth login` before any other command. Check with `sentry auth status`.
+- **Missing `--json` for piping**: Human-readable output includes formatting. Use `--json` when parsing output programmatically.
+- **Org/project ambiguity**: Auto-detection scans for DSNs in `.env` files and source code. If the project is ambiguous, specify explicitly: `sentry issue list my-org/my-project`.
+- **Confusing `--query` syntax**: The `--query` flag uses Sentry search syntax (e.g., `is:unresolved`, `assigned:me`), not free text search.
+- **Not using `--web`**: View commands support `-w`/`--web` to open the resource in the browser — useful for sharing links.