sentry-sdk-skill-creator

创建 Sentry SDK 技能包

生成一个完整、有研究支撑的 SDK 技能包 —— 一个主向导 SKILL.md，外加针对该 SDK 所支持的每个功能支柱的深入参考文件。

在以下情况调用此技能

• 被要求为新平台“创建 Sentry SDK 技能”
• 被要求向 sentry-agent-skills“添加 [语言/框架] 支持”
• 构建新的 sentry-<platform>-sdk 技能包
• 将 SDK 技能模式移植到新的 Sentry SDK

先阅读 ${SKILL_ROOT}/references/philosophy.md —— 它定义了此技能所实现的技能包架构、向导流程和设计原则。

---

阶段 1：确定 SDK

确定你要为哪个 SDK 构建技能：

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

确立功能矩阵 —— 该 SDK 支持哪些 Sentry 支柱？

支柱	查看文档	说明
错误监控	始终可用	不可妥协的基线
链路追踪/性能	通常可用	检查是否有 span API
性能分析	各不相同	可能已被移除或处于实验阶段
日志	较新的功能	检查最低版本
指标	较新的功能	可能处于 beta/实验阶段
Crons	仅后端	前端 SDK 不可用
会话回放	仅前端	后端 SDK 不可用
AI 监控	部分 SDK	通常仅 JS + Python

参考现有 SDK 技能，以了解目标质量水平：

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

---

阶段 2：研究

这是最关键的阶段。 技能质量完全取决于准确、最新的 API 知识。不要凭记忆编写技能 —— 针对每个功能参照官方文档进行研究。

研究策略

拆分出并行研究任务（使用带 outputFile 的 claude 工具）—— 每个功能领域一个任务。每个任务应：

1. 访问该功能的官方 Sentry 文档页面
2. 访问该 SDK 的 GitHub 仓库，进行源码级 API 验证
3. 将详尽的研究结果写入专门的研究文件

阅读 ${SKILL_ROOT}/references/research-playbook.md，了解详细的研究执行计划，包括提示词模板和文件命名约定。

研究 Sentry 向导

在深入研究功能之前，先检查 Sentry 向导 CLI 是否支持此框架：

# 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>"

如果存在向导集成：

1. 记录确切的向导命令和 -i 标志
2. 记录向导创建/修改的内容（文件、配置、构建插件）
3. 注意向导会以交互方式处理身份验证 —— 登录、组织/项目选择以及身份验证令牌的创建/下载都会自动完成
4. 注意向导是否会设置 source map 上传 —— 这对前端 SDK 至关重要
5. 这将成为所生成技能中阶段 3 的“选项 1：向导（推荐）”

为什么这很重要： 向导会自动处理整个身份验证流程（登录、组织/项目选择、 身份验证令牌）以及 source map 上传配置。没有 source map， 生产环境的堆栈追踪会显示压缩后的代码 —— 使 Sentry 在前端 调试中几乎毫无用处。而如果没有身份验证令牌，source map 根本无法上传。 向导是一步到位、可靠搞定这两者的最佳方式。

研究分批

按主题领域对研究任务进行分批。尽可能并行运行：

批次	主题	输出文件
1	设置、配置、所有初始化选项、框架检测	research/<sdk>-setup-config.md
2	错误监控、panic/异常捕获、作用域、数据增强	research/<sdk>-error-monitoring.md
3	追踪、性能分析（如支持）	research/<sdk>-tracing-profiling.md
4	日志、指标、定时任务（如支持）	research/<sdk>-logging-metrics-crons.md
5	会话回放（仅前端）、AI 监控（如支持）	research/<sdk>-replay-ai.md

重要： 告诉每个研究任务将其输出写入文件（outputFile 参数）。不要内联使用研究结果——它们很大（每个 500–1200 行）。Worker 稍后会从磁盘读取它们。

研究质量关卡

在继续之前，验证每个研究文件：

• 有实际内容（不只是 Claude 的过程笔记）
• 包含带有真实 API 名称的代码示例
• 包含最低 SDK 版本
• 涵盖框架特定的差异

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

重新运行任何产出少于 100 行的研究任务——它很可能静默失败了。

---

阶段 3：创建主 SKILL.md

主 SKILL.md 实现哲学文档中的四阶段向导。保持聚焦——主文件应涵盖向导流程、快速开始配置、框架表格和参考分发。各个功能的深入细节属于 references/ 文件，而不是这里。要全面但不要冗余。

先收集上下文

在编写之前，运行一个侦察任务或阅读现有技能以了解惯例：

• Frontmatter 模式（name、description、license）
• “Invoke This Skill When” 触发短语
• 表格格式和代码示例风格
• 故障排除表格惯例

SKILL.md 结构

---
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
[wizard command, what it creates/modifies table, skip-to-verification note]
### 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]

主 SKILL.md 的关键原则

1. 保持精简——深入细节放在参考中，而不是这里
2. 对框架 SDK 以向导为先——如果 Sentry 向导支持此框架，在任何手动设置之前将其呈现为“Option 1: Wizard (Recommended)”。向导处理完整的认证流程（登录、组织/项目选择、认证令牌创建）、source map 上传、构建工具插件和框架特定的接线——全部在一个交互式步骤中完成。完整模式见 ${SKILL_ROOT}/references/philosophy.md。
3. Source map 对前端/移动端不可妥协——手动设置路径必须包含 source map 上传配置（构建工具插件 + 环境变量）。没有 source map，生产堆栈跟踪就是不可读的混淆代码。
4. 检测命令必须真实——针对实际项目测试它们
5. 推荐逻辑必须有主见——“always”、“when X detected”，而不是“maybe consider”
6. 快速开始配置应启用最多功能，并使用合理的默认值
7. 框架中间件表格——确切的导入路径、中间件调用和怪癖
8. 积极交叉链接——如果是 Go 后端，建议前端。如果是 Svelte 前端，建议后端。

---

阶段 4：创建参考文件

SDK 支持的每个功能支柱一个参考文件。这些是深入探讨——它们可以比主 SKILL.md 更长。

参考文件结构

# <Feature> — Sentry <Platform> SDK

> Minimum SDK: `<package>` vX.Y.Z+

## Configuration

## Code Examples
### Basic usage
### Advanced patterns
### Framework-specific notes (if applicable)

## Best Practices

## Troubleshooting
| Issue | Solution |
|-------|----------|

什么造就一个好的参考

阅读 ${SKILL_ROOT}/references/quality-checklist.md 获取完整的质量标准。

关键点：

• 可运行的代码示例——不是伪代码，不是截断的片段
• 配置选项的表格——类型、默认值、最低版本
• 每个模式一个完整示例——不要展示同一事物的 5 个变体
• 框架特定说明——当框架之间行为不同时指出
• 顶部标明最低 SDK 版本——始终如此
• 对局限性诚实——如果某个功能被移除（如 Go 性能分析），就说明这一点

特定功能指南

功能	需要涵盖的要点
错误监控	捕获 API、panic/异常恢复、作用域、信息补充（标签/用户/面包屑）、错误链、BeforeSend、指纹
跟踪	采样率、自定义 span、分布式跟踪、框架中间件、操作类型
性能分析	采样率配置、如何关联到跟踪，或如实注明“已移除/不可用”
日志记录	启用标志、日志记录器 API、与常用日志库的集成、过滤
指标	计数器/仪表/分布 API、单位、属性、基数管理最佳实践
定时任务	Check-in API、监控器配置、计划类型、心跳模式
会话回放	回放集成、采样率、隐私遮罩、画布/网络记录

前端/移动端 SDK 注意事项： Source map 上传配置应放在主 SKILL.md 中（第 3 阶段：指南），而非参考文件中。这是核心设置流程的一部分——每次前端生产部署都需要配置。涵盖构建工具插件、所需的环境变量（SENTRY_AUTH_TOKEN、SENTRY_ORG、SENTRY_PROJECT），并将 .env 添加到 .gitignore。

---

第 5 阶段：验证所有内容

请勿跳过此阶段。 SDK API 变更频繁。研究可能产生幻觉，执行者也可能捏造配置键。

API 验证

针对 SDK 的实际源代码，执行专门的验证：

Research prompt: "Verify these specific API names and signatures against
the <SDK> GitHub repo source code: [list every API from the skill files]"

常见问题包括：

• 配置选项名称大小写错误（SendDefaultPii 与 SendDefaultPII）
• 虚构不存在的配置键（experimental.tracing——请确认它确实存在）
• 使用已弃用的 API，而非现代替代方案（configureScope → getIsolationScope）
• 将已移除的功能列为可用（Go SDK 中的性能分析）
• 最低版本号错误

审查

对完整的技能包进行审查：

• 代码示例的技术准确性
• 主 SKILL.md 与参考文件之间的一致性
• 与仓库中现有 SDK 技能的一致性
• 是否符合 Agent Skills 规范（frontmatter、命名）

修复审查发现的问题

按优先级分类处理：

• P0：误导性说法（宣传已移除的功能）——立即修复
• P1：API 错误、已弃用的方法——合并前修复
• P2：风格不一致、版本细节问题——如能快速修复则处理
• P3：跳过

---

第 6 阶段：注册并更新文档

技能通过审查后：

1. 更新 README.md —— 将其添加到 SDK Skills 表格
2. 更新 AGENTS.md —— 如果理念文档或技能分类部分需要更新
3. 添加使用示例 —— 在 Usage 部分添加触发短语
4. 记录技能包模式 —— 如果这是一个新的 SDK，请注明 references/ 结构

提交策略

每个主要部分单独提交：

1. feat(<platform>-sdk): add sentry-<platform>-sdk main SKILL.md wizard
2. feat(<platform>-sdk): add reference deep-dives for all feature pillars
3. docs(readme): add sentry-<platform>-sdk to available skills
4. fix(skills): address review findings（如有）

---

检查清单

宣布技能完成前：

• 已阅读并遵循理念文档
• 已根据官方文档（而非凭记忆）研究所有功能支柱
• 已验证研究文件（内容真实、API 正确、每个文件超过 100 行）
• 主 SKILL.md 内容聚焦——向导流程 + 快速入门 + 参考文档导航；深入内容放在参考文档中
• 主 SKILL.md 实现了全部 4 个向导阶段
• 已检查向导 CLI——若受支持，则以“选项 1：向导（推荐）”的形式呈现，并说明身份验证流程和源映射的优势
• 在手动设置路径中涵盖源映射／调试符号上传（前端／移动 SDK）
• 为每个受支持的功能支柱提供参考文件
• 已根据 SDK 源代码验证 API
• 已完成审查，并处理所有发现的问题
• 如实记录性能分析／已移除的功能（不作宣传）
• 已添加指向配套前端／后端技能的交叉链接
• 已更新 README.md
• 所有提交都经过润色，并使用描述性提交消息