sciagent-skill-creator

SciAgent スキル作成ツール

skills/ エントリー用のリポジトリローカルなスキャフォールダーです。AGENTS.md のステップ 1、2、4、5、6 の定型作業を自動化し、執筆作業をフィールドの設定ではなく コンテンツ（使用するタイミング、ワークフロー、レシピ、参考資料）に集中できるようにします。

このスキルを呼び出すタイミング

• 特定のツール、ライブラリ、データベース、ガイドのトピックについて、新しい SciAgent スキルエントリーをユーザーが求めている場合
• ユーザーが /sciagent-skill-creator を直接呼び出した場合
• エージェントが registry.yaml を手動で編集し、skills/<cat>/<name>/SKILL.md を一から作成しようとしている場合 — 代わりにこれを使用してください

次の場合は呼び出さないでください：

• 既存エントリーのコンテンツを編集する場合（ファイルを直接編集してください）
• 既存エントリーを移行する場合（まず AGENTS.md の「既存エントリーからの移行」を読んでください — スキャフォールダーが生成するのは骨組みですが、移行にはコンテンツに関する判断が必要です）
• registry.yaml のみを更新する場合（通常の編集を使用してください）

ユーザーから収集する情報

スキャフォールドスクリプトを実行する前に、以下を収集してください — ユーザーに見えないフラグで渡すのではなく、会話の中で確認してください。

1. トピック — 具体的なツール、ライブラリ、概念の名前です。「ML 関連」のように曖昧な場合は、明確化の質問をしてください。
2. サブタイプ — pipeline | toolkit | database | guide。AGENTS.md のステップ 1b にある判断基準を使用してください。不明な場合はユーザーに確認してください。
3. カテゴリ — 主カテゴリのディレクトリです。ユーザーがわからない場合は、AGENTS.md のステップ 2 にある表を提示してください。
4. エントリー名 — ケバブケースのスラッグです。規則：{tool-name}-{purpose}（例：pydeseq2-differential-expression）。ユーザーに確認してください。
5. ライセンス — 基盤となるツールのライセンスです。オリジナルの文章のみで構成されるコンテンツの場合は、既定値として CC-BY-4.0 を使用してください。
6. 説明 — 1～2 文、最大 1024 文字です。最初の 120 文字以内にツール／ドメインのキーワードを入れてください。避けるべきパターンは AGENTS.md のステップ 5「説明の執筆ルール」に記載されています。
7. タグ（任意）— エントリーが複数カテゴリに実質的にまたがる場合のみ指定してください（例：scientific-writing に分類される文献 DB に、["databases", "literature"] を付ける）。

スキャフォールディング前の重複チェック

スキャフォールドスクリプトを実行する前に、レジストリと legacy/ で類似した名前を検索してください。

grep -i "<topic-keyword>" registry.yaml
ls legacy/ | grep -i "<topic-keyword>"

ほぼ重複するエントリーがある場合は、続行する前にユーザーに伝えてください。並行するエントリーを新たに作成する場合、通常は重複ではなく既存エントリーの更新が必要です。

スキャフォールダーの実行方法

scripts/scaffold.py を明示的な引数付きで呼び出してください。このスクリプトは非対話型です — エージェントがすべての値を指定します。

python .claude/skills/sciagent-skill-creator/scripts/scaffold.py \
  --sub-type pipeline \
  --category genomics-bioinformatics \
  --name my-tool-purpose \
  --description "MyTool short-form description starting with the tool name. Brief on inputs, outputs, when to pick this over alternatives." \
  --license MIT \
  --tags databases,literature   # optional, comma-separated

動作：

1. 名前を検証します（ケバブケースであること、registry.yaml に未登録であること、legacy/ に存在しないこと）
2. カテゴリが skills/ 配下のディレクトリとして存在することを検証します
3. validate_description.py を使って説明を検証します（文字数と、先頭 120 文字以内にキーワードが含まれていること）
4. タグが指定されている場合、タグを検証します（ケバブケースであること）
5. 一致するテンプレートから skills/{category}/{name}/SKILL.md を作成し、フロントマターのフィールドを置き換えます
6. date_added を今日の日付（UTC）として、新しいエントリーを registry.yaml に追加します
7. pixi run validate を実行し、レジストリが引き続き適切な形式であることを確認します
8. 次の手順（概要、ワークフロー、レシピ、参考資料の記入）を表示します

検証に失敗すると、スクリプトは何も書き込まずに中断します。問題のある値を修正して、再実行してください。

スキャフォールディング後

生成された SKILL.md は、プレースホルダーを含む骨組みです。エージェントに残された作業は次のとおりです。

1. Overview、When to Use、Prerequisites、Workflow / Core API / Key Concepts、Common Recipes、Troubleshooting、References を記入します
2. サブタイプで必須となるセクション構成に合わせます（AGENTS.md のステップ 4 の形式ルールを参照）
3. pixi run test を実行します — validate だけでなくテストスイート全体を実行し、サブタイプ固有の構造上の不備（コードブロック数、表の行数、セクションの有無）を確認します

スキャフォールドスクリプトは、コンテンツまで作成するかのように装うことはありません。コンテンツの作成は、エージェントとソース資料に委ねられます。

コンテンツ作成ルール（SKILL.md に含めてはいけない内容）

スキルでは、ツールの分析対象を記述します。利用者のスタイルガイドではありません。SKILL.md は、さまざまな後続タスクを行う多くのエージェントに読まれます。特定の分析依頼に合った視覚的な選択を含めると、以降のすべての呼び出しに影響します。コミットする前に、次の内容を取り除いてください。

• カラーパレット、カラーマップ、テーマ — 16 進数コード（#08306b）、LinearSegmentedColormap.from_list(...)、ListedColormap([...])、およびカラーマップがツールの API 自体である場合（独自のパレットを提供するツールなど）を除く、指定された cmap= 引数は含めないでください。matplotlib のデフォルトを使い、利用者が後続処理で上書きできるようにします。
• 反復ごと／条件ごとのカラー辞書 — 例：colors = {"rep1": "#1f77b4", ...}。matplotlib が色を自動で循環させます。
• 特定のレポート向けに調整したフォント、dpi のプリセット、図のサイズ — 通常の折れ線グラフに使う figsize=(8, 4) は問題ありませんが、スライド資料に合わせて選んだ figsize=(12, 4) は含めないでください。
• 一度限りのユーザー依頼に関する具体的な指定 — ユーザーが自身の分析で「低い値は青、高い値は赤」と指定した場合、その指定はスキルではなくユーザーのコードに記述します。スキルでは phi/psi 密度の計算方法を説明し、色の付け方は利用者に委ねます。
• ツールのデフォルト以外のハードコードされたパス — 説明用の出力としての "figures/"、"results/"、f"{pdb_id}_protein.pdb" は問題ありませんが、"/Users/me/proj42/output" は含めないでください。

残す内容：分析ロジック、データの形状、単位、パラメーターの意味、想定される出力の構造（列、軸、単位）、およびツール自体が強制する視覚的な選択。

判断の目安：後続の利用者がその選択を上書きするなら、スキルに含めないでください。

文体：簡潔に

SKILL.md はエージェント向けのリファレンス資料であり、チュートリアルではありません。トークンのコストは重要です。取得されるたびに、すべての行にコストがかかります。手順の説明ではなく、ドキュメントとして書いてください。

• 各セクションの導入は 1 文にする。断定を避ける表現（「通常は」「一般に」「〜するとよいでしょう」）、埋め草（「なお」「言うまでもありませんが」）、婉曲表現を省き、ルールを明示します。
• コードブロック内のコメントは必要なものだけにする。単位、注意点、このパラメーターを使う理由など、ひと目で分からない行だけを説明します。コードの内容を繰り返すコメント（traj = md.load(...) の上にある # load the trajectory など）は不要です。
• 可能なら説明文よりコードを使う。同じ呼び出しを説明する段落より、4 行のコードブロックのほうが適切です。エージェントはコードを実行し、説明文はコードで示せない内容に使います。
• コードの前置きは不要。「以下のスニペットは、〜する方法の一例です」のような文は削除します。見出しとコードだけで内容が伝わります。
• 最後のまとめは不要。必要な情報が終わったら、そのセクションも終わりです。「要約すると」や「上で示したとおり」は不要です。
• セクション間の重複を削る。ワークフローのステップ 2 ですでにパラメーターを示している場合、「主なパラメーター」表の行で再説明する必要はありません。パラメーター名だけを記載します。
• 列挙には箇条書きではなく表を使う。パラメーター、トラブルシューティング、コードは表にします。説明文で列挙すると縦に長くなります。

目標密度：ファイルをざっと読む人が、説明文を約 5 行読むうちに次のコードブロックへ進めるようにします。セクションの説明文がコードより長い場合は、簡潔にしてください。

このスキルのファイル

• SKILL.md — このファイル（いつ、どのように、何をするか）
• scripts/scaffold.py — 非対話型スキャフォルダー（ファイルを作成し、レジストリに追記して、検証を実行）
• scripts/validate_description.py — 説明文のリンター（長さと先頭 120 文字のキーワードルール）。scaffold.py と単体で再利用されます。

ユーザーに伝える失敗モード

• 名前がすでに存在する → 別の接尾辞を提案する
• カテゴリが一覧にない → カテゴリ表を提示して確認する
• 説明文が停止語（Use、A、An、The、Query）で始まる → ツール名を先頭にして書き直す
• 説明文が長すぎる → 識別に関する末尾の部分を削り、キーワードを含む部分は残す
• スキャフォルダー実行後に pixi run validate が失敗する → レジストリの状態に一貫性がないため、中断して部分的な書き込みを元に戻す（スクリプトが自動で実行します。検証結果をそのまま報告してください）