sentry-sdk-skill-creator

すべてのスキル > SDK スキルクリエーター

Sentry SDK スキルバンドルを作成する

完全な、調査に基づく SDK スキルバンドルを作成します。メインのウィザード SKILL.md と、SDK がサポートする各機能の柱を詳しく解説するリファレンスファイルで構成されます。

このスキルを使用する場合

• 新しいプラットフォーム向けに「Sentry SDK スキルを作成して」と依頼された場合
• sentry-agent-skills に「[言語／フレームワーク] のサポートを追加して」と依頼された場合
• 新しい sentry-<platform>-sdk スキルバンドルを作成する場合
• Sentry SDK の新しい 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 の機能の柱を確認します。

機能の柱	ドキュメントで確認すること	備考
エラーモニタリング	常に利用可能	必須の基本機能
トレーシング／パフォーマンス	通常は利用可能	スパン API の有無を確認
プロファイリング	SDK によって異なる	削除されている場合や、実験的な場合があります
ロギング	新しい機能	最低バージョンを確認
メトリクス	新しい機能	最低バージョンを確認
クロン	バックエンドのみ	フロントエンド 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 知識にかかっています。記憶に頼ってスキルを書いてはいけません。すべての機能を公式ドキュメントで調査してください。

調査戦略

機能領域ごとに 1 つずつ、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	エラーモニタリング、パニック／例外の捕捉、スコープ、情報の拡充	research/<sdk>-error-monitoring.md
3	トレーシング、プロファイリング（サポートされている場合）	research/<sdk>-tracing-profiling.md
4	ロギング、メトリクス、cron（サポートされている場合）	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 では、philosophy ドキュメントに記載された4 フェーズのウィザードを実装します。内容を絞り、メインファイルではウィザードの流れ、クイックスタート設定、フレームワークの表、参照先への案内を扱います。各機能の詳細はここではなく、references/ ファイルに記載してください。徹底しつつ、重複は避けます。

まずコンテキストを確認する

作成前に、scout を実行するか既存のスキルを読んで、慣例を把握してください。

• 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：ウィザード（推奨）」として提示してください。ウィザードにはブラウザーでの対話的なログインが必要なため、エージェントは実行できません。ユーザー自身のターミナルにコマンドをコピー＆ペーストするよう案内し、完了したら戻ってくるよう、引用ブロックで伝えてください。ユーザーがウィザードをスキップした場合は、エージェントが手動セットアップをすべて行います。詳しい手順は ${SKILL_ROOT}/references/philosophy.md を参照してください。
3. フロントエンド／モバイルではソースマップが必須 — 手動セットアップでは、ソースマップのアップロード設定（ビルドツールのプラグインと環境変数）を必ず含めてください。ソースマップがなければ、本番環境のスタックトレースは圧縮された読みづらいコードになります。
4. 検出コマンドは実際に使えるものにする — 実際のプロジェクトでテストしてください
5. 推奨の判断基準は明確にする — 「常に」「X が検出された場合」のように記述し、「検討してもよい」といった表現は避けてください
6. クイックスタート設定では、妥当なデフォルト値を用いてできるだけ多くの機能を有効にする
7. フレームワークのミドルウェア表 — 正確なインポートパス、ミドルウェアの呼び出し方、注意点を記載する
8. 積極的に相互リンクする — Go バックエンドの場合はフロントエンドも提案します。Svelte フロントエンドの場合はバックエンドも提案します。

---

フェーズ 4：参照ファイルを作成する

SDK がサポートする機能の柱ごとに、参照ファイルを 1 つ作成します。これらは詳細な解説であり、メインの 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 を読んでください。

主なポイント：

• 実際に動作するコード例 — 擬似コードや途中で省略されたスニペットではなく、実行可能なものを記載します
• 設定オプションは表にまとめる — 型、デフォルト値、最低バージョンを記載します
• 各パターンにつき、完全な例を 1 つ掲載する — 同じ内容のバリエーションを 5 つ示すのは避けます
• フレームワーク固有の注意事項 — フレームワークによって動作が異なる場合は明記します
• 最低 SDK バージョンを冒頭に記載する — 必ず記載してください
• 制限事項を正直に伝える — Go のプロファイリングのように機能が削除されている場合は、その旨を記載します

機能固有のガイダンス

機能	主な記載事項
エラー監視	キャプチャ API、パニック／例外からの復旧、スコープ、拡充（タグ／ユーザー／パンくず）、エラーチェーン、BeforeSend、フィンガープリント
トレーシング	サンプルレート、カスタムスパン、分散トレーシング、フレームワークのミドルウェア、操作タイプ
プロファイリング	サンプルレートの設定、トレースへの紐付け方、または「削除済み／利用不可」と正直に記載
ロギング	有効化フラグ、ロガー API、一般的なロギングライブラリとの連携、フィルタリング
メトリクス	カウンター／ゲージ／分布 API、単位、属性、カーディナリティに関するベストプラクティス
Cron	チェックイン API、モニター設定、スケジュールの種類、ハートビートのパターン
セッションリプレイ	リプレイの連携、サンプルレート、プライバシーマスキング、キャンバス／ネットワークの記録

フロントエンド／モバイル SDK に関する注意: ソースマップのアップロード設定は、リファレンスファイルではなく、メインの 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 ではなく、非推奨 API を使用（configureScope → getIsolationScope）
• 削除済みの機能を利用可能と記載（Go SDK のプロファイリング）
• 最小バージョン番号の誤り

レビュー

完成したスキルバンドルをレビューします：

• コード例の技術的な正確性
• メインの SKILL.md とリファレンスファイル間の一貫性
• リポジトリ内の既存 SDK スキルとの一貫性
• Agent Skills 仕様への準拠（フロントマター、命名）

レビュー指摘事項の修正

優先度に従ってトリアージします：

• 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（該当する場合）

---

チェックリスト

スキルを完成とする前に、以下を確認してください。

• Philosophy ドキュメントを読み、内容に従っている
• すべての機能の柱を公式ドキュメントに基づいて調査している（記憶に頼っていない）
• 調査ファイルを検証している（実際の内容があり、API が正しく、それぞれ 100 行を超えている）
• メインの SKILL.md が要点に絞られている — ウィザードの流れ、クイックスタート、リファレンスへの案内が中心で、詳細はリファレンスに記載している
• メインの SKILL.md でウィザードの 4 つのフェーズをすべて実装している
• ウィザード CLI を確認している — 対応している場合は「オプション 1：ウィザード（推奨）」として提示し、認証フローとソースマップの利点を説明している
• 手動セットアップの手順で、ソースマップ／デバッグシンボルのアップロードを扱っている（フロントエンド／モバイル SDK）
• 対応する機能の柱ごとにリファレンスファイルがある
• SDK のソースコードに照らして API を検証している
• レビューを完了し、指摘事項に対処している
• プロファイリング／削除された機能について、誇張せず正直に記載している
• 関連するフロントエンド／バックエンドスキルへの相互リンクがある
• README.md を更新している
• すべてのコミットを、内容が分かる説明的なメッセージに整えている