authoring-security-skills

セキュリティスキルの作成

スキルがコンテキスト予算に見合う価値を得るのは、モデルがそれなしでは誤るであろう内容を担うときです。モデルはすでに nmap -sV の動作を知っています。しかし、報告前に実証された影響までたどること、修正前に証拠を保全すること、本番環境のノイズに対して一度もテストしていないルールのリリースを拒むことといった、規律を確実に身につけているわけではありません。

成果物となるのは、その判断力です。コマンドは、それを支える足場にすぎません。

使用する場面

• secskills-offense、-defense、または -core に新しいスキルを追加するとき
• 過剰に詰め込まれたスキルを分割するとき、または重複する2つのスキルを統合するとき
• 誤ったリクエストで読み込まれる、または正しいリクエストで読み込まれないスキルを修正するとき
• validate.py、sync_attack.py、または run_evals.py での失敗を解決するとき

使用しない場面

• 自分が書いた内容の事実確認をするとき。これは verifying-skill-accuracy の役割であり、この手順の後に実施する別のゲートです
• 既存の、内容が確定したスキルの文章を編集するとき
• スキルに関係のないリポジトリレベルの作業（マニフェスト、マーケットプレイス、CI）

ステップ1：プラグインを選ぶ

スキルが属するプラグインは必ず1つです。この分割により、ブルーチームのユーザーがエクスプロイトの内容を持ち込まずに済み、その逆も同様です。

プラグイン	対象	テスト
secskills-offense	エクスプロイト、攻撃者の手法、ターゲットに対して実行するテスト	エンゲージメント中に、誰かのシステムに対して実行する内容ですか？
secskills-defense	DFIR、ハンティング、検知、インテリジェンス、インシデント対応	事後にアーティファクトを調査する内容ですか、それとも検知を構築する内容ですか？
secskills-core	デュアルユース：リバースエンジニアリング、コード／暗号／サプライチェーンのレビュー、AI セキュリティ、ATT&CK マッピング、レポート作成	どちらの側にも同じように適していますか？

2つのプラグインに当てはまる場合は、重複を避けて core を選びます。プラグインをまたぐ参照は想定されており、片方のプラグインだけをインストールした読者には機能しないテキストとして扱われます。これは意図的な仕様なので、相互参照を避けるためにスキルを重複させないでください。

ステップ2：ティアを選ぶ

ドメインスキルは、分野全体の方法論を担い、幅広い自然言語のリクエストで起動します。数を絞り、互いに重複しないようにしてください。

手順スキルは、特定のターゲットとツールチェーンの組み合わせを扱います。一般知識からは推測できない、まれで具体的な組み合わせです。たとえば、blutter を使う reversing-flutter-apps です。範囲を狭くするのが本来の目的です。

ティアを適切に機能させるためのルールは2つです。

1. すべての手順スキルには、ドメインスキルからたどり着けるようにします。 識別のための確認事項と、ドメインスキルへの振り分けの記述を追加します。たどり着けない手順スキルは無用の長物です。
2. 手順スキルは次のスキルへ引き継ぎます。 シンボルの復元は評価そのものではありません。作業を引き継ぐスキルの名前を示してください。

迷ったら、そのスキルが対象分野のほとんどのエンゲージメントに適用されるのか（ドメイン）、それとも特定のアーティファクトが手元にある場合に限られるのか（手順）を考えてください。

ステップ3：説明を書く

スキルで最も効果の大きい文章です。 Claude がスキルを読み込むかどうかはこの文章で判断され、71個ある他のスキルすべてと競合します。説明が曖昧だと、本文が完璧なスキルでも実行されません。

バリデーターが検証するルール：三人称、60～1024文字、トリガー句を含むこと。バリデーターでは検証できないものの、レビュアーが確認するルール：

• スキルが何をするかを最初に述べ、その後に具体的な状況を挙げて Use when ... と続けます。
• トリガーは、抽象的な概念ではなく、ユーザーが実際に手元に持っているもの（ファイル名、マジックバイト、フレームワーク名やツール名、エラー文字列、識別に役立つ症状）を基に組み立てます。
• 最も近い類似スキルと区別できる証拠を明示します。

# Good — names artifacts, tools, and the symptom
description: Reverse engineer and intercept traffic from Flutter/Dart mobile
  apps using blutter, reFlutter, and Frida. Use when an APK or IPA contains
  libflutter.so, libapp.so, App.framework, or flutter_assets, when jadx shows
  only a thin Dart wrapper, or when Burp sees no traffic from an app that is
  clearly online.

# Bad — overlaps the domain skill and triggers on the wrong requests
description: Advanced mobile reverse engineering techniques for modern apps.

ステップ 4：本文を書く

必須セクション：

• ## When to Use — カテゴリではなく、具体的な状況を記載します。
• ## When NOT to Use — 別のスキルが適切な場面を記載し、該当する兄弟スキルをバッククォートで囲んで明記します。これにより、複数のスキルが同じ言葉を取り合うのを防ぎます。

セキュリティスキルで必須のセクション：

• ## Rationalizations to Reject — 見落としにつながる、もっともらしく聞こえる近道と、それが誤りである理由をそれぞれ記載します。これはコレクションの中でも最も価値の高いセクションです。コマンド一覧では表せない判断基準を示します。

攻撃を扱うスキルには、その分野で実際に生じるリスクに即した対象範囲と許可に関する説明も必要です。定型文では不十分です。偵察では第三者の資産や、個人データとしての OSINT が問題になります。パスワードクラッキングでは、アカウントロックアウトが可用性リスクになります。RF 作業では、電波を対象内にとどめられないため、盗聴や周波数帯に関する法律が問題になります。一般的な「まず許可を得ること」という文言には価値がありません。

スキルのワークフローで公開資料を読む場合（アドバイザリ、仕様書、RFC、ベンダーレポート、ATT&CK ページなど）は、## References の前に標準の ## Reading External Sources ブロックを含めます。このブロックは、該当するスキル（producing-threat-intelligence、auditing-supply-chain）から一字一句そのままコピーしてください。スキル間で内容を同一に保ち、差異が生じないようにする必要があります。公開ドキュメントを defuddle.md 経由で処理することで、トークンを大幅に節約し、全文を検索可能な形で取得できます。

ネットワーク通信の対象がターゲットであるスキルには、このブロックを追加しないでください。クラウドメタデータのエンドポイント、ターゲット自身のサービス、データ流出先ホスト、フィッシング URL、C2 は直接取得する必要があります。サードパーティの抽出ツール経由にすると、コマンドが壊れ、作戦の URL が漏えいし、実稼働中の敵対インフラの場合はオペレーターに気づかれるおそれがあります。

手順は実行順に並べ、その順序を明示してください。 技法を順不同に並べただけの本文は、参照されても実行されません。最初に行う操作を「即時」、その出力に依存する操作を「次に」、ターゲットに接触する操作を「実行時」として示します。そうすれば、作業の途中でスキルを読み込んだ読者も、自分がどの段階にいるか把握できます。この順序付けは安全性にもつながります。「実行時」のグループの操作はすべて、許可が与えられていることを条件とします。グループが明確に区別されていなければ、その条件を理解できません。

スキルとは実行すべき指示のまとまりであり、読んだことを確認するための文書ではありません。 スキルを読み込んで「読んで理解しました」と返すだけで終わるのは失敗です。最初の手順を飛ばしやすい場合は、その失敗パターンを本文で明示する価値があります。たとえば、「何にも触れる前に対象範囲を記録する」ことから始まるスキルは、急いでいる読者が実行せずに要約してしまいがちなスキルです。

記憶ではなく、判断力を促す文章を書いてください。

こう書く	こう書かない
ある技法を別の技法より選ぶ理由と、その技法が失敗する場合	ツールのフラグ一覧
報告前に検証結果が満たすべき条件	「脆弱性を報告する」
分野で起こりがちな失敗を明示する	一般的なベストプラクティスの注意喚起

SKILL.md は 600 行未満にしてください。ペイロード一覧や長い表は references/ ディレクトリに移してください。このディレクトリは、明示的に参照された場合にのみ読み込まれます。参照を連鎖させないでください。SKILL.md から参照ファイルを指定することはできますが、そのファイルからさらに別のファイルへ誘導してはいけません。

バリデーターは、バッククォートで囲まれた参照パスをすべて実在するファイルとして解決する点に注意してください。そのため、説明文中の例示的なパスはビルドに失敗します。実在するファイルのみを記載してください。

ステップ 5：ATT&CK インデックスに登録する

スキルがマッピングされておらず、かつ未マッピングとして宣言されてもいない場合、sync_attack.py は失敗します。 生成された SKILL.md 内のブロックではなく、secskills-core/ttp-index.json を編集してください。

マッピングする場合：対象とする各手法の skills 配列に、そのスキルを追加します。

{"id": "T1595", "name": "Active Scanning", "tactics": ["TA0043"],
 "skills": ["performing-reconnaissance", "enumerating-network-services"]}

または、Enterprise ATT&CK が適用されない理由を宣言します。

"_unmapped": {
  "securing-ai-systems": "MITRE ATLAS (AML.T####) and the OWASP Top 10 for LLM / Agentic Applications"
}

その後、再生成します。## ATT&CK Coverage ブロックは生成されるため、手動で編集するのは常に誤りです。

python3 scripts/sync_attack.py --write

ステップ 6：評価ケースを追加する

ルーティングは実際に起こりうる失敗モードであり、それを検出するのが評価セットです。evals/cases.jsonl にケースを追加します。1 行に 1 つの JSON オブジェクトを記述します。

{"id": "adcs-esc1-certipy-vuln-template",
 "query": "certipy find -vulnerable flagged a template with ENROLLEE_SUPPLIES_SUBJECT and low-priv enrollment — how do I turn this into domain admin?",
 "expect_skill": "abusing-adcs",
 "also_acceptable": ["attacking-active-directory"],
 "expected_behavior": ["Identify this as an ESC1 escalation path",
                       "Request a cert specifying an alternate UPN",
                       "PKINIT with the cert to obtain the target's TGT/NT hash"],
 "trap_for": ["attacking-active-directory", "attacking-kerberos-delegation"]}

query は、ツールの出力やエラー、手元にある成果物を含め、実際のユーザーが入力するような内容にします。サニタイズされたクエリでは何も証明できません。

重要なフィールドは trap_for です。 このクエリをルーティングしてはならないスキルを列挙します。新しいスキルはすべて、少なくとも 1 つの近接スキルのケースの trap_for に含める必要があります。また、それぞれの新しいスキルは、最も近い近接スキルを対象にしたケースを少なくとも 1 つ持つ必要があります。これだけが、説明の肥大化を防ぐための機械的な歯止めです。

ステップ 7：検証する

PR を出す前に、次の 3 つすべてに合格する必要があります。

python3 scripts/validate.py --strict     # form, manifests, verified count
python3 scripts/sync_attack.py --check   # ATT&CK blocks match the index
python3 scripts/run_evals.py --check     # every skill covered, no bad refs

その後、プラグインの .claude-plugin/plugin.json と .claude-plugin/marketplace.json のバージョンを更新します。バリデーターは両者の一致を強制します。また、CHANGELOG.md にエントリーを追加します。スキル数が変わった場合は、プラグインの説明に記載されたスキル数も更新してください。数がずれていると、validate.py が警告します。

スキルに「検証済み」の印を付けない

新しいコンテンツは、定義上、未検証のドラフトです。書いたばかりのスキルに verified: 日付を絶対に追加しないでください。 verifying-skill-accuracy に渡し、検証可能な主張をすべて一次ソースに照らして確認してください。全範囲を確認できた場合にのみ、検証済みの印を付けます。

3 つすべてのバリデーターに合格しても、検証済みとは限りません。バリデーターが確認するのは形式です。このリポジトリで最初に検証した際には、CI がすべて成功していたファイルから、事実誤認が 31 件見つかりました。

退けるべき合理化

• 「説明は大体合っていればよく、重要なのは本文だ。」 読み込まれないスキルには本文がありません。説明の品質は、その成果が利用されるかどうかを決める最大の要因です。
• 「確実に発動するよう、説明を広くしておこう。」 広すぎる説明は、範囲を明確にした類似スキルからトラフィックを奪い、実際の作業で間違ったスキルを読み込ませます。コレクション全体をうまく組み合わせるには、正確さが重要です。
• 「既存のスキルと重複するが、自分のほうがうまくカバーできる。」 それなら、既存のスキルを修正してください。同じクエリを奪い合う 2 つのスキルは、どちらの品質も低下させます。
• 「ほとんどコマンドだから、注意点は明らかだ。」 明らかなら、わざわざ書き残す必要はありません。モデルがすでに持っているのはコマンドの一覧です。足りないのは判断力です。
• 「ATT&CK ブロックは手作業で追加するほうが速い。」 これは生成されます。手作業で編集しても次回の同期で上書きされ、同期するまでは --check に失敗します。
• 「評価は形式的なものだ。」 大規模なコレクションで実際に最もよく起こる失敗はルーティングエラーです。説明がいつの間にか広がるのを検出できるのは、trap_for ケースだけです。
• 「コマンドをテストしたから検証済みだ。」 自分の環境でテストして確認できるのは、その環境で実行できることだけです。識別子、デフォルト値、ID が読者の使うバージョンでも正しいかどうかは確認できません。それは別途検証する必要があります。

参考資料

• verifying-skill-accuracy — この手順の後に実行するファクトチェックのゲート
• CONTRIBUTING.md — マージ基準、プロジェクトのスタイル、PR の要件
• secskills-core/ttp-index.json — テクニックとスキルの対応表
• evals/README.md — 評価ハーネスとケースの形式