読み込み中

スキルとは、組織が自らの組織的知識を運用可能にする手段です。その指示は明示的で、バージョン管理され、広く適用され、ポリシーが変更された際には中央で更新されます。基本原則はこうです。一貫して適用されなければならない組織的知識についてはスキルを書き、CLAUDE.md やプロンプトに属するコンポーネントについてはスキルを書かないことです。

はじめに

  • 前提条件:特に必要ありません。CLAUDE.md があると役立ちます。これはエージェントの作業知識をリポジトリ内に保持できるためですが、スキルはそれに依存しません。
  • インフラ:名前付きの所有者と、文書化された信頼できる情報源を持つ1つのポリシー。

実行方法

  1. 現在一貫して適用されていない知識を1つ選びます。これはセキュリティ標準、API設計の規約、またはブランドルールなどが考えられます。
  2. それをスキルとして書きます。スキルとは、フロントマターにトリガー条件を記し、本文に実行内容を記した SKILL.md を含むフォルダです。エンジニアは、ポリシー所有者の信頼できる情報源から、Claudeの助けを借りてこれを書きます。
  3. スキルをリポジトリ内の .claude/skills/<name>/ に配置してコードと一緒に配布するか、プラグインを通じて組織全体に配布します。
  4. スキルがトリガーされることをテストします。Claudeに関連するタスクをさまざまな方法で依頼し、毎回スキルが読み込まれることを確認します。
  5. ポリシーが変更されたら、スキルを変更し、ポリシー所有者にその変更を承認してもらいます。
  6. エンジニアは次回のセッションで自動的に新しいバージョンを取得します。

実際の例

.claude/skills/secure-api-review/SKILL.md:

markdown
---
name: secure-api-review
description: Apply the API security standard. Use whenever creating or
  modifying an external-facing endpoint, reviewing API code, or
  generating an OpenAPI spec.
---
# Secure API review
When you create or change an API endpoint:
1. Authentication: every endpoint requires the gateway JWT;
   no anonymous routes outside /health.
2. Input validation: validate request bodies against the OpenAPI
   schema and reject unknown fields.
3. Audit: every state-changing endpoint emits an audit event with
   actor, action, entity and timestamp.
4. Data classification: fields tagged pii in the schema must never
   appear in logs or error messages.
Run scripts/check-endpoints.sh and include its output in your summary.

ガバナンス上の考慮事項

スキルは統制の一種ですが、あくまで助言的なものです。コードが書かれている間にClaudeがそのポリシーを適用しやすくするものであり、セッションにそれを強制的に遵守させるものではありません。常に守られなければならないポリシーには、スキルの背後に決定論的な仕組みが必要です。たとえば、その操作をブロックするフックや、PR時にポリシーを再チェックするレビューパスなどです。スキルは違反を稀にし、フックは違反をほぼ不可能にします。フックは編集時点で違反を捕捉し、プルリクエストに対する同じチェックは、別の経路でブランチに到達したものを捕捉します。スキルの呼び出しはセッショントレースに記録され、ポリシー所有者はスキルの変更をコードと同様にレビューします。

測定方法

  • 先行指標:ポリシー所有者がポリシー変更を承認してから、更新されたスキルがマージされるまでの時間。スキルフォルダに対するPRから取得します。
  • 遅行指標:ポリシーを引用するPRレビューの指摘事項。これは、コードが書かれている間にスキルがポリシーを適用するようになれば、ゼロに向かって減少するはずです。指摘事項がゼロに向かって減少しない場合、スキルがトリガーされていないか、その文言が公式ポリシーから逸脱している可能性があります。

ビルド時のガードレールとしてのフック

スキルは助言的な統制であり、フックはその背後にある決定論的な層です。Claudeの操作の大半は実装中のファイル編集とシェルコマンドであるため、ビルドフェーズはフックが最も頻繁に発火する場面になりがちです。

ビルドフェーズのフックは以下のことができます。

  • 生成されたクラスや凍結されたパッケージなど、保護されたパスへの編集をブロックする
  • ファイル編集後にフォーマッタとリンタを実行し、ドリフトが蓄積しないようにする
  • 認証情報が差分に含まれないようにする
  • 例外なく守られなければならないポリシーを持つスキルを裏付ける

フックはそれに一致する各操作で実行されるため、ビルドフェーズのフックは高速で、変更されたファイルに範囲を絞るべきです。完全なテストスイートのような重いチェックは、コミット時またはPR時に行うべきです。

これは、このページで先ほど示した secure-api-review スキルのルール4の背後にあるフックです。このリポジトリは保険会社のものであり、そのエンドポイントファイルは claims-api/routes/ にあります。これらのファイルのいずれかが編集されるたびに、フックは scripts/check-endpoints.sh を実行します。これはリポジトリのルートにあるスクリプトで、スキルが既に名前を挙げているものです。そのスクリプトは、OpenAPIスキーマで pii とタグ付けされたフィールドがログ呼び出しや発生したエラーに到達した場合に失敗します。

このフックは .claude/settings.json に登録されています。空の args リストにより、Claude Codeはシェルを経由せずにスクリプトを直接実行します。

json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/api-policy.sh",
            "args": [] }
        ]
      }
    ]
  }
}

フックスクリプト .claude/hooks/api-policy.sh:

bash
#!/bin/bash
# secure-api-reviewスキルのルール4を、スキルが実行するものと同じスクリプトで裏付けます。
file=$(jq -r '.tool_input.file_path')
case "$file" in
  "$CLAUDE_PROJECT_DIR"/claims-api/routes/*.py) ;;
  *) exit 0 ;;                                   # not an endpoint
esac
cd "$CLAUDE_PROJECT_DIR" || exit 2
if ! found=$(scripts/check-endpoints.sh "${file#"$CLAUDE_PROJECT_DIR"/}"); then
  echo "secure-api-review rule 4: a pii field reaches a log or an error message." >&2
  echo "$found" >&2
  exit 2
fi

編集後に実行されるフックはその編集を取り消すことができないため、終了コード2はスクリプトのメッセージをClaudeの前に提示し、Claudeがその行を修正できるようにします。顧客の名前をログに記録する編集の後、Claudeがスクリプトから見るメッセージは次のとおりです。

text
secure-api-review rule 4: a pii field reaches a log or an error message.
claims-api/routes/status.py:10: policy_holder_name

シェルコマンドがファイルを書き換える場合、Edit|Write フックは発火しません。そのため、同じスクリプトはすべてのプルリクエストに対する必須チェックとしても実行されます。

yaml
name: API policy
on: pull_request
jobs:
  check-endpoints:          # a required check in branch protection
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: scripts/check-endpoints.sh claims-api/routes/*.py

人間の承認を求めるフックは、ステージ5:デプロイのゲートに属します。なぜなら、ビルド中に承認プロンプトを出すと、並行して実行されているすべてのセッションのクリティカルパス上に人間が戻ってしまうからです。