Agent Skills

1---
2name: "sentry"
3description: "Use when the user asks to inspect Sentry issues or events, summarize recent production errors, or pull basic Sentry health data via the Sentry API; perform read-only queries with the bundled script and require `SENTRY_AUTH_TOKEN`."
4---
5 
6 
7# Sentry (Read-only Observability)
8 
9## Quick start
10 
11- If not already authenticated, ask the user to provide a valid `SENTRY_AUTH_TOKEN` (read-only scopes such as `project:read`, `event:read`) or to log in and create one before running commands.
12- Set `SENTRY_AUTH_TOKEN` as an env var.
13- Optional defaults: `SENTRY_ORG`, `SENTRY_PROJECT`, `SENTRY_BASE_URL`.
14- Defaults: org/project `{your-org}`/`{your-project}`, time range `24h`, environment `prod`, limit 20 (max 50).
15- Always call the Sentry API (no heuristics, no caching).
16 
17If the token is missing, give the user these steps:
181. Create a Sentry auth token: https://sentry.io/settings/account/api/auth-tokens/
192. Create a token with read-only scopes such as `project:read`, `event:read`, and `org:read`.
203. Set `SENTRY_AUTH_TOKEN` as an environment variable in their system.
214. Offer to guide them through setting the environment variable for their OS/shell if needed.
22- Never ask the user to paste the full token in chat. Ask them to set it locally and confirm when ready.
23 
24## Core tasks (use bundled script)
25 
26Use `scripts/sentry_api.py` for deterministic API calls. It handles pagination and retries once on transient errors.
27 
28## Skill path (set once)
29 
30```bash
31export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
32export SENTRY_API="$CODEX_HOME/skills/sentry/scripts/sentry_api.py"
33```
34 
35User-scoped skills install under `$CODEX_HOME/skills` (default: `~/.codex/skills`).
36 
37### 1) List issues (ordered by most recent)
38 
39```bash
40python3 "$SENTRY_API" \
41  list-issues \
42  --org {your-org} \
43  --project {your-project} \
44  --environment prod \
45  --time-range 24h \
46  --limit 20 \
47  --query "is:unresolved"
48```
49 
50### 2) Resolve an issue short ID to issue ID
51 
52```bash
53python3 "$SENTRY_API" \
54  list-issues \
55  --org {your-org} \
56  --project {your-project} \
57  --query "ABC-123" \
58  --limit 1
59```
60 
61Use the returned `id` for issue detail or events.
62 
63### 3) Issue detail
64 
65```bash
66python3 "$SENTRY_API" \
67  issue-detail \
68  1234567890
69```
70 
71### 4) Issue events
72 
73```bash
74python3 "$SENTRY_API" \
75  issue-events \
76  1234567890 \
77  --limit 20
78```
79 
80### 5) Event detail (no stack traces by default)
81 
82```bash
83python3 "$SENTRY_API" \
84  event-detail \
85  --org {your-org} \
86  --project {your-project} \
87  abcdef1234567890
88```
89 
90## API requirements
91 
92Always use these endpoints (GET only):
93 
94- List issues: `/api/0/projects/{org_slug}/{project_slug}/issues/`
95- Issue detail: `/api/0/issues/{issue_id}/`
96- Events for issue: `/api/0/issues/{issue_id}/events/`
97- Event detail: `/api/0/projects/{org_slug}/{project_slug}/events/{event_id}/`
98 
99## Inputs and defaults
100 
101- `org_slug`, `project_slug`: default to `{your-org}`/`{your-project}` (avoid non-prod orgs).
102- `time_range`: default `24h` (pass as `statsPeriod`).
103- `environment`: default `prod`.
104- `limit`: default 20, max 50 (paginate until limit reached).
105- `search_query`: optional `query` parameter.
106- `issue_short_id`: resolve via list-issues query first.
107 
108## Output formatting rules
109 
110- Issue list: show title, short_id, status, first_seen, last_seen, count, environments, top_tags; order by most recent.
111- Event detail: include culprit, timestamp, environment, release, url.
112- If no results, state explicitly.
113- Redact PII in output (emails, IPs). Do not print raw stack traces.
114- Never echo auth tokens.
115 
116## Golden test inputs
117 
118- Org: `{your-org}`
119- Project: `{your-project}`
120- Issue short ID: `{ABC-123}`
121 
122Example prompt: “List the top 10 open issues for prod in the last 24h.”
123Expected: ordered list with titles, short IDs, counts, last seen.
124