sentry-sdk-skill-creator

What this skill does

> [All Skills](../../SKILL_TREE.md) > SDK Skill Creator

# Create a Sentry SDK Skill Bundle

Produce a complete, research-backed SDK skill bundle — a main wizard SKILL.md plus deep-dive reference files for every feature pillar the SDK supports.

## Invoke This Skill When

- Asked to "create a Sentry SDK skill" for a new platform
- Asked to "add support for [language/framework]" to sentry-agent-skills
- Building a new `sentry-<platform>-sdk` skill bundle
- Porting the SDK skill pattern to a new Sentry SDK

> Read `${SKILL_ROOT}/references/philosophy.md` first — it defines the bundle architecture, wizard flow, and design principles this skill implements.

---

## Phase 1: Identify the SDK

Determine what you're building a skill for:

```bash
# What SDK? What's the package name?
# Examples: sentry-go, @sentry/sveltekit, sentry-python, sentry-ruby, sentry-cocoa
```

Establish the **feature matrix** — which Sentry pillars does this SDK support?

| Pillar | Check docs | Notes |
|--------|-----------|-------|
| Error Monitoring | Always available | Non-negotiable baseline |
| Tracing/Performance | Usually available | Check for span API |
| Profiling | Varies | May be removed or experimental |
| Logging | Newer feature | Check minimum version |
| Metrics | Newer feature | Check minimum version |
| Crons | Backend only | Not available for frontend SDKs |
| Session Replay | Frontend only | Not available for backend SDKs |
| AI Monitoring | Some SDKs | Usually JS + Python only |

**Reference existing SDK skills** to understand the target quality level:

```bash
ls skills/sentry-*-sdk/ 2>/dev/null
# Read 1-2 existing SDK skills for pattern reference
```

---

## Phase 2: Research

**This is the most critical phase.** Skill quality depends entirely on accurate, current API knowledge. Do NOT write skills from memory — research every feature against official docs.

### Research Strategy

Spin off **parallel research tasks** (using the `claude` tool with `outputFile`) — one per feature area. Each task should:
1. Visit the official Sentry docs pages for that feature
2. Visit the SDK's GitHub repo for source-level API verification
3. Write thorough findings to a dedicated research file

Read `${SKILL_ROOT}/references/research-playbook.md` for the detailed research execution plan, including prompt templates and file naming conventions.

### Research the Sentry Wizard

Before diving into feature research, check whether the Sentry wizard CLI supports this framework:

```bash
# Check the SDK's docs landing page for wizard instructions
# Visit: https://docs.sentry.io/platforms/<platform>/
# Look for: "npx @sentry/wizard@latest -i <integration>"
```

If a wizard integration exists:
1. Document the exact wizard command and `-i` flag
2. Document what the wizard creates/modifies (files, config, build plugins)
3. Note that the wizard handles **authentication interactively** — login, org/project selection, and auth token creation/download all happen automatically
4. Note whether the wizard sets up **source map upload** — this is critical for frontend SDKs
5. This will become "Option 1: Wizard (Recommended)" in Phase 3 of the generated skill

> **Why this matters:** The wizard handles the entire auth flow (login, org/project selection,
> auth token) and source map upload configuration automatically. Without source maps,
> production stack traces show minified code — making Sentry nearly useless for frontend
> debugging. And without the auth token, source maps can't be uploaded at all. The wizard
> is the most reliable way to get both right in a single step.

### Research Batching

Batch research tasks by topic area. Run them in parallel where possible:

| Batch | Topics | Output file |
|-------|--------|-------------|
| 1 | Setup, configuration, all init options, framework detection | `research/<sdk>-setup-config.md` |
| 2 | Error monitoring, panic/exception capture, scopes, enrichment | `research/<sdk>-error-monitoring.md` |
| 3 | Tracing, profiling (if supported) | `research/<sdk>-tracing-profiling.md` |
| 4 | Logging, metrics, crons (if supported) | `research/<sdk>-logging-metrics-crons.md` |
| 5 | Session replay (frontend only), AI monitoring (if supported) | `research/<sdk>-replay-ai.md` |

**Important:** Tell each research task to write its output to a file (`outputFile` parameter). Do NOT consume research results inline — they're large (500–1200 lines each). Workers will read them from disk later.

### Research Quality Gate

Before proceeding, verify each research file:
- Has actual content (not just Claude's process notes)
- Contains code examples with real API names
- Includes minimum SDK versions
- Covers framework-specific variations

```bash
# Quick verification
for f in research/<sdk>-*.md; do
  echo "=== $(basename $f) ==="
  wc -l "$f"
  grep -c "^#" "$f"  # should have multiple headings
done
```

**Re-run any research task that produced fewer than 100 lines** — it likely failed silently.

---

## Phase 3: Create the Main SKILL.md

The main SKILL.md implements the **four-phase wizard** from the philosophy doc. Keep it focused — the main file should cover the wizard flow, quick start config, framework tables, and reference dispatch. Deep-dive details for individual features belong in `references/` files, not here. Be thorough but not redundant.

### Gather Context First

Before writing, run a scout or read existing skills to understand conventions:
- Frontmatter pattern (name, description, license)
- "Invoke This Skill When" trigger phrases
- Table formatting and code example style
- Troubleshooting table conventions

### SKILL.md Structure

```markdown
---
name: sentry-<platform>-sdk
description: Full Sentry SDK setup for <Platform>. Use when asked to "add Sentry
  to <platform>", "install <package>", or configure error monitoring, tracing,
  [features] for <Platform> applications. Supports [frameworks].
license: Apache-2.0
---

# Sentry <Platform> SDK

## Invoke This Skill When
[trigger phrases]

## Phase 1: Detect
[bash commands to scan project — package manager, framework, existing Sentry, frontend/backend]

## Phase 2: Recommend
[opinionated feature matrix with "always / when detected / optional" logic]

## Phase 3: Guide
### Option 1: Wizard (Recommended)   ← if wizard exists for this framework
[blockquote telling the user to run the wizard themselves — it requires interactive browser login. Include the command in a copy-pasteable code block inside the blockquote. Tell them to come back when done. Add a line after the blockquote: "If the user skips the wizard, proceed with Option 2 (Manual Setup) below."]
### Option 2: Manual Setup            ← always include
### Install
### Quick Start — Recommended Init
### Source Maps Setup                  ← required for frontend/mobile SDKs
### Framework Middleware (if applicable)
### For Each Agreed Feature
[reference dispatch table: feature → ${SKILL_ROOT}/references/<feature>.md]

## Configuration Reference
[key init options table, environment variables]

## Verification
[test snippet]

## Phase 4: Cross-Link
[detect companion frontend/backend, suggest matching SDK skills]

## Troubleshooting
[common issues table]
```

### Key Principles for the Main SKILL.md

1. **Keep it lean** — deep details go in references, not here
2. **Wizard-first for framework SDKs** — if the Sentry wizard supports this framework, present it as "Option 1: Wizard (Recommended)" before any manual setup. **The wizard requires interactive browser login and cannot be run by the agent** — present it in a blockquote telling the user to copy-paste the command into their own terminal, and come back when done. If the user skips the wizard, the agent proceeds with full manual setup. See `${SKILL_ROOT}/references/philosophy.md` for the full pattern.
3. **Source maps are non-negotiable for frontend/mobile** — the manual setup path must include source map upload configuration (build tool plugin + env vars). Without source maps, production stack traces ar