为新平台创建 Sentry SDK…

当需要为某个语言/框架新建 sentry-<platform>-sdk 技能包时，用研究驱动的方式产出主 SKILL.md 向导与各功能支柱的深度参考文件。

适用场景

解决思路

1. 先阅读 ${SKILL_ROOT}/references/philosophy.md，理解技能包架构、向导流程与设计原则。
2. Phase 1 识别 SDK：确定目标 SDK 与包名（如 sentry-go、@sentry/sveltekit、sentry-python、sentry-ruby、sentry-cocoa），并建立功能矩阵，逐项确认该 SDK 支持哪些 Sentry 支柱（Error Monitoring 始终可用；Tracing/Performance 通常可用，检查 span API；Profiling 视情况，可能已移除或实验性；Logging 较新，检查最低版本；Metrics 较新，检查最低版本；Crons 仅后端；Session Replay 仅前端；AI Monitoring 通常仅 JS + Python）。
3. 参考已有 SDK 技能以对齐目标质量：执行 `ls skills/sentry-*-sdk/ 2>/dev/null`，阅读 1-2 个现有 SDK 技能作为模式参考。
4. Phase 2 研究（最关键阶段）：不要凭记忆写技能，每个功能都要对照官方文档研究；用 `claude` 工具配合 `outputFile` 并行拆分研究任务，每个任务访问该功能的官方 Sentry 文档页、访问 SDK 的 GitHub 仓库做源码级 API 验证，并把完整发现写入专门的研究文件；详细执行计划（含提示词模板与文件命名约定）见 ${SKILL_ROOT}/references/research-playbook.md。
5. 研究 Sentry 向导：访问 https://docs.sentry.io/platforms/<platform>/，查找 `npx @sentry/wizard@latest -i <integration>`；若存在向导集成，记录确切的向导命令与 `-i` 标志、记录向导创建/修改的内容（文件、配置、构建插件）、说明向导会交互式处理认证（登录、组织/项目选择、auth token 创建与下载均自动完成）、说明向导是否配置 source map 上传（对前端 SDK 至关重要），这些将成为生成技能 Phase 3 中的 “Option 1: Wizard (Recommended)”。
6. 按主题分批并行研究：批次 1 为 Setup、配置、所有 init 选项、框架检测，输出 `research/<sdk>-setup-config.md`；批次 2 为错误监控、panic/异常捕获、scopes、enrichment，输出 `research/<sdk>-error-monitoring.md`；批次 3 为 Tracing、Profiling（若支持），输出 `research/<sdk>-tracing-profiling.md`；批次 4 为 Logging、Metrics、Crons（若支持），输出 `research/<sdk>-logging-metrics-crons.md`；批次 5 为 Session Replay（仅前端）、AI Monitoring（若支持），输出 `research/<sdk>-replay-ai.md`。
7. 要求每个研究任务把输出写入文件（`outputFile` 参数），不要内联消费研究结果（每个文件 500–1200 行），后续由 worker 从磁盘读取。
8. 研究质量门禁：确认每个研究文件有实际内容（不是 Claude 的过程笔记）、包含真实 API 名称的代码示例、包含最低 SDK 版本、覆盖框架特定差异；用 `for f in research/<sdk>-*.md; do echo "=== $(basename $f) ==="; wc -l "$f"; grep -c "^#" "$f"; done` 快速验证；任何少于 100 行的研究任务都要重跑（很可能静默失败）。
9. Phase 3 创建主 SKILL.md：实现 philosophy 文档中的四阶段向导，保持聚焦——主文件只覆盖向导流程、快速开始配置、框架表和参考分发，单个功能的深度细节放到 `references/` 文件，做到详尽但不冗余。
10. 写之前先收集上下文：运行 scout 或阅读现有技能，了解 frontmatter 模式（name、description、license）、“Invoke This Skill When” 触发短语、表格格式与代码示例风格、故障排查表约定。
11. 按指定结构编写 SKILL.md：frontmatter（name 为 sentry-<platform>-sdk，description 说明用途与支持框架，license 为 Apache-2.0）；Invoke This Skill When 触发短语；Phase 1: Detect（扫描项目的 bash 命令——包管理器、框架、现有 Sentry、前端/后端）；Phase 2: Recommend（带 “always / when detected / optional” 逻辑的有主见功能矩阵）；Phase 3: Guide（Option 1: Wizard (Recommended)（若该框架有向导）、Option 2: Manual Setup（始终包含）、Install、Quick Start — Recommended Init、Source Maps Setup（前端/移动端必需）、Framework Middleware（若适用）、For Each Agreed Feature（功能 → ${SKILL_ROOT}/references/<feature>.md 的分发表））；Configuration Reference（关键 init 选项表、环境变量）；Verification（测试片段）；Phase 4: Cross-Link（检测配套前端/后端，建议匹配的 SDK 技能）；Troubleshooting（常见问题表）。
12. 主 SKILL.md 的关键原则：保持精简，深度细节放 references；框架 SDK 向导优先——若 Sentry 向导支持该框架，在任何手动设置之前先呈现为 “Option 1: Wizard (Recommended)”，且向导需要交互式浏览器登录、agent 无法运行，要用 blockquote 让用户把命令复制粘贴到自己终端并在完成后回来，若用户跳过向导则 agent 继续完整手动设置（完整模式见 ${SKILL_ROOT}/references/philosophy.md）；前端/移动端 source maps 不可妥协——手动设置路径必须包含 source map 上传配置（构建工具插件 + 环境变量），否则生产堆栈跟踪是不可读的压缩代码；检测命令必须真实，要在实际项目上测试；推荐逻辑必须有主见，用 “always”“when X detected” 而非 “maybe consider”；Quick Start 配置应启用最多功能并带合理默认值；框架中间件表要给出确切导入路径、中间件调用与坑点；积极交叉链接（Go 后端就建议前端，Svelte 前端就建议后端）。
13. Phase 4 创建参考文件：为 SDK 支持的每个功能支柱创建一个参考文件，这些是深度内容，可比主 SKILL.md 更长；结构为标题 `# <Feature> — Sentry <Platform> SDK`、`> Minimum SDK: `<package>` vX.Y.Z+`、Configuration、Code Examples（Basic usage / Advanced patterns / Framework-specific notes）、Best Practices、Troubleshooting 表（Issue | Solution）。
14. 参考文件质量要求（完整评分标准见 ${SKILL_ROOT}/references/quality-checklist.md）：可运行的代码示例（不是伪代码、不是截断片段）；配置选项用表格（类型、默认值、最低版本）；每个模式只给一个完整示例（不要同一件事给 5 个变体）；框架特定说明（行为在不同框架间不同时要点出）；顶部始终写最低 SDK 版本；诚实说明限制（如 Go profiling 已移除就直说）。
15. 按功能覆盖要点：Error Monitoring 覆盖捕获 API、panic/异常恢复、scopes、enrichment（tags/user/breadcrumbs）、错误链、BeforeSend、fingerprinting；Tracing 覆盖采样率、自定义 span、分布式追踪、框架中间件、操作类型；Profiling 覆盖采样率配置、如何附着到 trace，或诚实写 “removed/not available”；Logging 覆盖启用开关、logger API、与流行日志库集成、过滤；Metrics 覆盖 counter/gauge/distribution API、单位、属性、基数最佳实践；Crons 覆盖 check-in API、monitor 配置、schedule 类型、心跳模式；Session Replay 覆盖 replay 集成、采样率、隐私遮罩、canvas/网络录制。
16. 前端/移动端 SDK 注意：source map 上传配置属于主 SKILL.md 的 Phase 3: Guide，而不是参考文件——它是核心设置流程的一部分，每个前端生产部署都需要；要覆盖构建工具插件、必需环境变量（`SENTRY_AUTH_TOKEN`、`SENTRY_ORG`、`SENTRY_PROJECT`），并把 `.env` 加入 `.gitignore`。
17. Phase 5 验证一切（不可跳过）：对 SDK 实际源码做专门的 API 验证，提示词为 “Verify these specific API names and signatures against the <SDK> GitHub repo source code: [list every API from the skill files]”；常见错误包括配置项大小写错误（`SendDefaultPii` vs `SendDefaultPII`）、捏造不存在的配置键（如 `experimental.tracing`）、使用已废弃 API（`configureScope` → `getIsolationScope`）、把已移除功能列为可用（Go SDK 的 profiling）、最低版本号错误。
18. 对完整技能包跑一次 reviewer：代码示例的技术准确性、主 SKILL.md 与参考文件的一致性、与仓库中现有 SDK 技能的一致性、Agent Skills 规范合规（frontmatter、命名）。
19. 按优先级处理评审发现：P0 误导性声明（宣传已移除功能）立即修复；P1 错误 API、废弃方法合并前修复；P2 风格不一致、版本小问题能快改就改；P3 跳过。
20. Phase 6 注册并更新文档：更新 README.md 加入 SDK Skills 表；必要时更新 AGENTS.md（philosophy 文档或技能分类部分）；在 Usage 部分添加触发短语示例；若是新 SDK，记录 references/ 结构。
21. 提交策略：每大块单独提交——`feat(<platform>-sdk): add sentry-<platform>-sdk main SKILL.md wizard`、`feat(<platform>-sdk): add reference deep-dives for all feature pillars`、`docs(readme): add sentry-<platform>-sdk to available skills`、`fix(skills): address review findings`（若有）。
22. 完成前核对清单：已阅读并遵循 philosophy 文档；所有功能支柱均从官方文档研究（非凭记忆）；研究文件已验证（真实内容、正确 API、每个 >100 行）；主 SKILL.md 聚焦（向导流程 + 快速开始 + 参考分发，深度内容在 references）；主 SKILL.md 实现全部 4 个向导阶段；已检查向导 CLI——若支持则呈现为 “Option 1: Wizard (Recommended)” 并描述认证流程与 source map 好处；手动设置路径覆盖 source map / debug symbol 上传（前端/移动端 SDK）；每个支持的功能支柱都有参考文件；API 已对照 SDK 源码验证；评审通过且发现已处理；Profiling/已移除功能诚实记录（不宣传）；交叉链接到配套前端/后端技能；README.md 已更新；所有提交信息清晰完整。

适用边界 · 注意事项

• 不适用于非 Sentry SDK 的技能创建（本技能专用于构建 sentry-<platform>-sdk 技能包）。
• 不要在未完成官方文档与 SDK 源码研究的情况下凭记忆编写技能内容。
• 不要跳过 Phase 5 验证——SDK API 变化频繁，研究可能产生幻觉，worker 可能捏造配置键。