sentry-sdk-skill-creator

所有技能 > SDK 技能创建器

创建 Sentry SDK 技能包

制作一套完整、基于研究的 SDK 技能包——包含主向导 SKILL.md，以及为 SDK 支持的每个功能支柱提供的深入参考文件。

何时调用此技能

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

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

---

第 1 阶段：确定 SDK

确定要为哪个对象创建技能：

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

建立功能矩阵——此 SDK 支持哪些 Sentry 功能支柱？

功能支柱	检查文档	备注
错误监控	始终可用	不可或缺的基线功能
追踪/性能	通常可用	检查 span API
性能分析	因 SDK 而异	可能已移除或处于实验阶段
日志记录	较新功能	检查最低版本
指标	较新功能	检查最低版本
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. 说明向导是否会设置源映射上传——这对前端 SDK 至关重要
5. 这将成为生成技能第 3 阶段中的“选项 1：向导（推荐）”

为什么这很重要： 向导会自动处理整个身份验证流程（登录、选择组织/项目、 身份验证令牌），并配置源映射上传。没有源映射，生产环境中的堆栈跟踪会显示压缩后的代码， 这会让 Sentry 几乎无法用于前端调试。而且没有身份验证令牌，就完全无法上传源映射。 向导是通过单个步骤可靠完成这两项配置的最佳方式。

研究任务分批

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

批次	主题	输出文件
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 行）。之后由工作线程从磁盘读取这些文件。

研究质量门槛

继续之前，检查每份研究文件：

• 包含实际内容（而非只有 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）
• “在以下情况下调用此技能”触发语
• 表格格式和代码示例风格
• 故障排除表格惯例

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
[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]

主 SKILL.md 的关键原则

1. 保持精简——深入细节放在参考文档中，而非主文件里
2. 框架 SDK 优先采用向导——如果 Sentry 向导支持该框架，应先将其作为“选项 1：向导（推荐）”介绍，再介绍任何手动设置。向导需要交互式浏览器登录，Agent 无法运行——应使用引用块告知用户将命令复制粘贴到自己的终端中，完成后再回来。如果用户跳过向导，Agent 将继续执行完整的手动设置。完整模式请参阅 ${SKILL_ROOT}/references/philosophy.md。
3. 前端/移动端的源映射不可或缺——手动设置流程必须包含源映射上传配置（构建工具插件 + 环境变量）。没有源映射，生产环境中的堆栈跟踪就会变成无法读取的压缩代码。
4. 检测命令必须真实可用——针对实际项目进行测试
5. 建议逻辑必须明确果断——使用“始终”“检测到 X 时”等表述，不要说“可以考虑”
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
• 所有提交都经过润色，并使用描述性提交消息