devtu-optimize-skills

ToolUniverse スキルの最適化

エビデンスの評価と出典の明記を備えた、高品質なリサーチスキルのベストプラクティスです。

ツール品質基準

1. エラーメッセージは対処可能な内容にする — 何が問題だったかに加え、ユーザーが何をすべきかを伝えます
2. スキーマを実際の API に合わせる — python3 -m tooluniverse.cli run <Tool> '<json>' を実行して確認します
3. データ範囲を明確にする — 含まれていないデータを明記します
4. API 呼び出しの前に入力を検証する — 無効な値を黙って送信しないでください
5. ツール間の振り分けを行う — クエリの範囲外であれば、適切なツール名を伝えます
6. パラメーターを黙って破棄しない — パラメーターが無視される場合は、その旨を伝えます

基本原則（13 のパターン）

詳細：references/optimization-patterns.md

#	パターン	主な考え方
1	ツールインターフェースの検証	初回の呼び出し前に get_tool_info() を実行し、修正内容の表を維持します
2	基盤データレイヤー	まずアグリゲーター（Open Targets、PubChem）にクエリします
3	バージョン付き識別子	ENSG00000123456 と .12 バージョンの両方を取得します
4	まず曖昧さを解消する	ID を解決し、衝突を検出して、除外フィルターを作成します
5	レポートのみの出力	レポートには説明を記載し、方法論は求められた場合のみ付録に記載します
6	エビデンスの評価	T1（機序）→ T2（機能）→ T3（関連）→ T4（言及）
7	完全性の定量化	セクションごとに数値の最低基準を設けます（>=20 PPIs、上位 10 組織など）
8	必須チェックリスト	「エビデンスは限定的」とする場合でも、すべてのセクションを設けます
9	データ不足の集約	不足データを単一のセクションに集約します
10	クエリ戦略	高精度なシード → 引用の拡張 → 衝突を除外した広範な検索
11	ツール障害への対応	プライマリ → フォールバック 1 → フォールバック 2 → 利用不可であることを記録
12	スケーラブルな出力	説明レポート + JSON/CSV 形式の参考文献一覧
13	統合セクション	論文の一覧だけでなく、生物学的モデル + 検証可能な仮説を提示します

最適化されたスキルのワークフロー

Phase -1: Tool Verification (check params)
Phase  0: Foundation Data (aggregator query)
Phase  1: Disambiguation (IDs, collisions, baseline)
Phase  2: Specialized Queries (fill gaps)
Phase  3: Report Synthesis (evidence-graded narrative)

テスト基準

詳細：references/testing-standards.md

重要なルール：すべてのツール呼び出しをテストする前に、スキルのドキュメントを作成してはいけません。

• スキルごとに 30 件以上のテストを実施し、合格率を 100% にします
• すべてのテストで実データを使用します（プレースホルダーは使用しません）
• フェーズテスト + 統合テスト + エッジケーステストを行います
• SOAP ツール（IMGT、SAbDab、TheraSAbDab）には operation パラメーターが必要です
• 一時的なエラー（再試行）と実際のバグ（修正）を区別します
• API ドキュメントは誤っていることが多いため、必ず実際に呼び出して確認します

パターン 14：ツール一覧ではなく推論フレームワーク（重要）

ツールをただ列挙するだけのスキル（「A を呼び出し、次に B、次に C を呼び出す」）は、有用性テストで 3～5/10 の評価になります。データの解釈方法や組み合わせ方を説明するスキルは、7～9/10 の評価になります。すべてのスキルに、以下を必ず含めてください。

14a. 解釈テーブル

生の API データを生物学的・臨床的な意味に対応付けます。取得するだけでなく、その意味を説明してください。

悪い例（ツール一覧）	良い例（推論フレームワーク）
「MGnify から GO 用語を取得する」	GO 用語 → 解釈テーブル：酪酸遺伝子 = バリアの完全性、LPS 遺伝子 = 炎症
「DepMap の依存性スコアを取得する」	スコア < -0.5 = 必須遺伝子。ただし、パンエッセンシャルは（毒性のため）薬剤標的として不適切で、選択的なものは適切な標的です
「FAERS の件数を取得する」	PRR > 5 = 強いシグナル。ただし、シグナル ≠ 因果関係（チャネリングバイアス、知名度バイアス）

14b. 統合フェーズ

複数フェーズにわたるスキルには、データを集めるだけでなく、「つまり何を意味するのか」に答える最終フェーズが必要です。

• 「何が、なぜ変化したのでしょうか？」
• 「これは原因でしょうか、それとも結果でしょうか？」
• 「実行可能な推奨事項は何でしょうか？」

14c. 限界を正直に示す

ツールの API でスキルが約束する内容を実現できない場合は、その旨を明示します。実現するとは限らない機能を説明しないでください。例：「DepMap_get_gene_dependencies が返すのは遺伝子のメタデータのみで、細胞株ごとの CRISPR スコアは返しません。」

パターン 15：ツールで対応できない場合の計算手順

一部の科学的解析では、API クエリだけでなく計算が必要です。ある機能に対応するツールがない場合は、ToolUniverse で利用できるパッケージ（pandas、scipy、numpy、statsmodels、biopython、networkx）を使った Python コードの手順をスキルに直接組み込みます。

計算手順を使用する場面：

不足している機能	手順	パッケージ
API が必要なデータを返さない場合（例：DepMap スコア）	CSV をダウンロードして pandas で分析	pandas
統計的検定（差次的存在量、エンリッチメント）	scipy.stats + FDR 補正	scipy, statsmodels
配列解析（アラインメント、保存性）	Biopython SeqIO + ペアワイズアラインメント	biopython
化学的類似性（類似体検索、フィンガープリント）	RDKit フィンガープリント + Tanimoto	rdkit（可視化は追加機能）
ネットワーク解析（ハブ遺伝子、クラスタリング）	NetworkX グラフ指標	networkx
スコアリングアルゴリズム（ACMG 分類、生存スコア）	カスタム Python 関数	組み込み
用量の実現可能性（Cmax と IC50 の比較）	数値比較 + PK データ	pandas, numpy

スキルにおける計算手順のテンプレート：

**Computational procedure: [Name]**
[When to use this: explain the gap it fills]

\`\`\`python
# [What this computes]
# Requires: [packages] (included in ToolUniverse dependencies)
import pandas as pd
from scipy.stats import mannwhitneyu

# Input: [describe expected input format]
# Output: [describe output]
# [Full working code with example data]
\`\`\`

[Interpretation guidance for the output]

計算手順の主なルール：

1. ToolUniverse の依存関係（pyproject.toml）に含まれるパッケージのみを使用します：pandas、scipy、numpy、networkx、requests、biopython（追加機能）
2. すぐにテストできるよう、サンプルデータを含めます
3. 出力について説明します — 解釈のないコードブロックは役に立ちません
4. 外部データのダウンロードが必要な場合は、その旨を記載します（例：depmap.org から DepMap CSV を取得）

パターン 15b：REST API がないデータセットのダウンロードと処理

重要な科学データセットの多くには REST API がありませんが、一括ダウンロード用ファイルが提供されています。必須データを取得する唯一の方法がこれである場合は、スキルに具体的なダウンロードと処理の手順を含めます。

ダウンロードと処理の手順のテンプレート：

**Step 1: Download data files**
- URL: [exact download page URL]
- Files needed: [filename] (~[size]) — [what it contains]
- Registration: [required/not required]
- Update frequency: [quarterly/annually/etc.]

**Step 2: Process with Python**
[Working code with pandas/scipy that loads the CSV and produces the analysis]

**Step 3: Interpret results**
[Table mapping output values to biological/clinical meaning]

**When files are not available**: [Fallback strategy using API tools]

スキルで参照される、ダウンロードのみ可能な既知のデータセット：

データセット	ダウンロード URL	ファイル	使用スキル
DepMap CRISPR	depmap.org/portal/download/all/	CRISPRGeneEffect.csv（約300MB）、Model.csv（約2MB）	functional-genomics, cell-line-profiling
TCGA 臨床データ	portal.gdc.cancer.gov	臨床データ + 変異 TSV	cancer-genomics-tcga
GTEx 発現データ	gtexportal.org/home/downloads	GTEx_Analysis_v8_Annotations.csv	expression-data-retrieval
ClinGen 遺伝子疾患データ	clinicalgenome.org/docs/	gene_curation_list.tsv	variant-interpretation
gnomAD 制約データ	gnomad.broadinstitute.org/downloads	制約指標 TSV	functional-genomics

重要なルール：ダウンロードできない場合に備えて、必ず代替手段を用意します（ユーザーが登録していない、ファイルが大きすぎるなど）。代替手段には、取得できるデータが不完全であっても、利用可能な API ツールを使用します。

よくあるアンチパターン

アンチパターン	修正方法
「検索ログ」の報告	方法論は内部に留め、発見事項のみを報告します
曖昧性の解消が不足	衝突検出を追加し、除外フィルターを構築します
根拠の評価がない	T1～T4 の評価を適用し、各主張にラベルを付けます
空のセクションを省略	「特定されず」と記載して含めます
統合的な分析がない	生物学的モデル + 仮説を追加します
失敗が表面化しない	Data Gaps に記録し、代替手段を実装します
ツールのパラメーターが誤っている	呼び出す前に get_tool_info() で確認します
GTEx が結果を返さない	バージョン付き ID ENSG*.version を試します
基盤レイヤーがない	まずアグリゲーターにクエリします
ツール呼び出しが未テスト	テスト駆動で進めます：最初にテストスクリプトを実行します
解釈のないツールカタログ	データの意味を説明する解釈テーブルを追加します
実現を確認していない機能	API で実現できない場合は正直に示し、代わりに計算手順を追加します
統計解析が不足	ツールでは実行できない計算のために、scipy/pandas のコード手順を追加します

ユーザーの不満への簡単な改善策

不満	改善策
「レポートが短すぎる」	フェーズ 0 の基盤整備とフェーズ 1 の曖昧さの解消を追加します
「ノイズが多すぎる」	衝突フィルタリングを追加します
「何が重要なのかわからない」	T1〜T4 のエビデンス階層を追加します
「セクションが不足している」	最低要件を定めた必須チェックリストを追加します
「長すぎて読みにくい」	ナラティブと JSON を分けます
「論文のリストにすぎない」	統合セクションを追加します
「ツールが失敗してデータがない」	再試行とフォールバックの連鎖を追加します

スキルのテンプレート

---
name: [domain]-research
description: [What + when triggers]
---

# [Domain] Research

## Workflow
Phase -1: Tool Verification → Phase 0: Foundation → Phase 1: Disambiguate
→ Phase 2: Search → Phase 3: Report

## Phase -1: Tool Verification
[Parameter corrections table]

## Phase 0: Foundation Data
[Aggregator query]

## Phase 1: Disambiguation
[IDs, collisions, baseline]

## Phase 2: Specialized Queries
[Query strategy, fallbacks]

## Phase 3: Report Synthesis
[Evidence grading, mandatory sections]

## Output Files
- [topic]_report.md, [topic]_bibliography.json

## Quantified Minimums
[Numbers per section]

## Completeness Checklist
[Required sections with checkboxes]

追加の参考資料

• 詳細なパターン：references/optimization-patterns.md
• テスト基準：references/testing-standards.md
• ケーススタディ（実際の改善事例 4 件）：references/case-studies.md
• チェックリスト（レビューとリリース）：references/checklists.md