pythia-skill-author

新しいスキルの作成

最初に伝えること：「pythia-skill-author を使います。実際の作業方法をまとめましょう。」

**フェーズ：**学習 → 質問 → 実行 — 聞き取り、スキーマを調査し、トリガーを検証します

スキルとは、二度と議論し直す必要がないように記録した判断です。誰かの記憶ではなく、データベースの根拠に基づいて、チームが実際に行っていることを記録してください。

ステップ 1 — 一度に 1 つずつ質問する

次の順に質問し、回答を待ちます。

1. どのタスクのためのスキルですか？» 1 つの懸念事項につき 1 つのスキルにします。「レポート手順の定型作業」は 1 つのスキルですが、「チームに関するすべて」は違います。
2. いつ起動すべきですか？ 開発者自身の言葉を集めます。開発者が入力するであろう語句（「làm báo cáo」、「clone the export proc」、エラーコード、ファイルパターンなど）です。これらを説明文にそのまま記載します。起動するかどうかは、これらの語句にかかっています。
3. どれが厳守すべきルールで、どれが好みですか？ 厳守すべきルールには「絶対遵守事項」と危険信号の表を設けます。好みについては「特に指示がなければ、これを既定とする」と記載します。
4. 誤りとはどのような状態ですか？ 過去のインシデントは、危険信号の行を作るうえで最適な材料です。

ステップ 2 — 根拠を調査する

記憶はあてになりませんが、スキーマは違います。書き始める前に、次の操作を行います。

• pythia similar <TYPICAL_NAME> → このワークフローを体現するプログラム群を確認します。上位の候補を pythia src で開き、実際の命名規則、パラメーター、構造に関する規約を抜き出します。
• pythia args / pythia cols で、スキルが使うよう指示するシグネチャと型を確認します。
• 例として、短い実際のコードをそのまま引用したスニペットを 2、3 個保存します。実際のコードは、創作したコードより優先されます。

ステップ 3 — チーム標準の形式で草案を書く

• フロントマター：フォルダー名と一致する kebab-case の name を設定します。description はトリガー条件（Use when ...）で始め、ステップ 1 で集めた開発者の語句を含めます。
• 本文は約 150 行以内にします。テンプレート、チェックリスト、スニペット集などの長い資料は reference/ に置き、貼り付けるのではなくリンクします。
• 構成の選択肢 — 回答に応じて必要なものを使い、それ以外は省略します：絶対遵守事項（1 行、大文字）· 番号付きワークフロー · 危険信号の表（「考え → 実際」）·「使用しない場合」· 最初に伝えることの行。
• チームが使う言語で書きます。このパックは英語ですが、個人用のチームスキルはベトナム語でもかまいません。開発者が決めます。

すべてにスキルが必要なわけではありません。 命名規則やスタイルのルールだけなら、.pythia/conventions.json（適用プレビューのたびに機械的にチェック）と .pythia/conventions.md（エージェントが読む説明文）に記載するほうが適しています。スキルは、手順、ゲート、判断を伴うワークフローのために使います。

ステップ 4 — 配置して、リントする

pythia skill new <name> --trigger <the developer's words> を実行すると、このパックの形式で .claude/skills/<name>/SKILL.md が生成されます。ステップ 1〜3 の内容を記入します。pythia skill lint は、各プロジェクトスキルがパックと同じ要件を満たしているかチェックします。具体的には、解析可能なフロントマター、Use when トリガー、フォルダー名と一致する名前、行数の上限、Phase 行、存在する参照先を確認し、問題があれば終了コード 2 で終了します。

ユーザースキルは開発者のプロジェクトに配置します。たとえば、Claude Code では .claude/skills/<name>/SKILL.md を使います（ほかのエージェントでは、npx skills add に対応する skills/<name>/SKILL.md のレイアウトが使えます）。インストール済みの pythia パックには書き込まないでください。更新時に上書きされるうえ、パックのリントではパック固有の固定スキル一覧が適用されます。

ステップ 5 — トリガーを検証する

新しいセッションで、開発者が実際に頼むときの言い方（ステップ 2 で集めた語句）でタスクを依頼します。スキルは、促されなくても起動しなければなりません。起動しない場合は、説明文に問題があります。失敗した正確な語句を加えて説明文を改善し、もう一度テストします。

最新の状態を保つ

開発者が同じ内容についてエージェントを 2 回修正したら、その修正をスキルに反映することを提案します。それがスキルの役目を果たしている証拠です。事実ではなくなったルールは削除してください。古くなったスキルは、スキルがないよりも悪い状態です。

チーム外に共有する前に

このパック自体に適用される衛生チェックを実行してください。スキルやその参照先に、ホスト名、スキーマ名、認証情報、内部識別子が含まれていないことを確認します。プライベートリポジトリでは問題なくても、公開リポジトリでは情報漏えいになります。

危険信号 — こんな考えが浮かんだら中止してください

考え	実際のところ
「このチャットの記憶を頼りに書こう」	まずsimilar／srcを調べてください。根拠となるのはコードベースです。
「あらゆる内容を網羅する大きなスキルを1つ作ろう」	スキルごとに対象を1つに絞ってください。そうしないと、適切にトリガーされません。
「スタイルガイドを丸ごと貼り付けよう」	目安は約150行です。長い内容はreference/に移してください。
「説明は一般的な内容でいい」	一般的な説明ではトリガーされません。開発者自身が使っている表現を使ってください。
「動くから、トリガーのテストは不要」	トリガーをテストしなければ、誰にも使われないスキルになってしまいます。