Claude Agent Skills 実践｜カスタムスキル作成・プラクティス・TIPS・セキュリティ

要約

本稿は Claude Agent Skills の 実践編 である。前編で概念を押さえたうえで、カスタムスキル作成の入り口となる skill-creator と評価ファイル evals.json、フロントマター全フィールドの解説、description 設計の 3 原則、サポートファイル分割・バリデーションループ、$ARGUMENTS や ultrathink などの TIPS、そしてアンチパターン全 12 種と ZDR（Zero Data Retention）対象外 というセキュリティ必須知識までを整理する。

この記事を読むことで得られるメリット

この記事を読むことで以下のことが分かる:

• skill-creator を使った最小構成からのスキル作成手順
• evals.json で「スキル有／無」の効果測定を行う方法
• フロントマター全フィールド（公式仕様＋ Claude Code 固有拡張）の使い分け
• description が発動しない主な 4 つの原因と対策
• allowed-tools による最小権限、context: fork によるサブエージェント実行
• アンチパターン 12 種の具体例と回避策
• Agent Skills が ZDR 契約対象外である理由と実務的対策

この記事を読むのにかかる時間

約 18 分

環境

• MacOS Apple M4 Max Sequoia 15.1
• Claude Code v2.1.x 系（skill-creator 同梱）
• 参照: agentskills.io 仕様 / Claude Code Docs "Frontmatter reference"

カスタムスキル作成の基本

入り口は skill-creator

カスタムスキル作成の第一歩は、Anthropic 公式の メタスキル である skill-creator を使うことである。skill-creator は対話形式で要件をヒアリングし、SKILL.md と評価用の evals.json まで自動生成する。

典型的な作成フローは以下の 4 ステップである。

1. スキル作成: 要件を対話的にヒアリング、SKILL.md + evals.json を生成
2. テスト実行: 生成された評価を実行して動作を確認
3. 改善反復: フィードバック → 修正 → 再テストのループ
4. description 最適化: 発動しやすさを調整して仕上げる

リポジトリは github.com/anthropics/skills/tree/main/skills/skill-creator にある。

evals.json の中身と役割

evals.json は skill-creator が生成する 評価セット である。スキルが期待通りに発動・出力するかを 機械検証可能な形式 で記述する。

copy{
  "skill_name": "csv-analyzer",
  "evals": [
    {
      "id": 1,
      "prompt": "Find top 3 months by revenue in data/sales.csv and make a bar chart.",
      "expected_output": "Bar chart of top 3 months with axes.",
      "files": ["evals/files/sales.csv"],
      "assertions": [
        "Bar chart file exists",
        "Chart shows 3 months",
        "Both axes labeled"
      ]
    }
  ]
}

各フィールドの役割は以下の通りである。

評価を実行すると以下の 3 つの成果物が得られる。

• with/without 比較: スキル有／無の差分で効果を測定
• grading.json: assertion ごとの PASS/FAIL と証拠
• benchmark.json: pass_rate / tokens / time の平均・標準偏差

「このスキルを追加して本当に性能が上がったのか？」を数字で示せる点が重要である。

フロントマター全フィールド

オープンスタンダード仕様のフィールド

agentskills.io の公式仕様で定義されているフィールドは以下である。

name の仕様差に注意したい。agentskills.io 仕様 ではディレクトリ名と一致する name の明示指定を推奨している。一方 Claude Code 実装 では省略時にディレクトリ名から自動推論される。ポータビリティを重視するなら明示指定がよい。

Claude Code 固有の拡張フィールド

Claude Code は公式スペックに加えて以下の実装固有フィールドを拡張している。

これらは Claude Code 上では便利だが、他プラットフォームへの移植時には無視される可能性があるため、ポータビリティ要件と相談して使う こと。

model: と effort: の指定

model: フィールドではエイリアス（opus / sonnet / haiku / best / opusplan / sonnet[1m] / opus[1m]）または完全な modelID（claude-opus-4-7 など）を指定できる。

未指定時はセッションの現行モデルを継承する。ただし context: fork や subagent との組み合わせでは挙動の曖昧性が報告されているため、重要なスキルでは明示指定を推奨する。context: fork 時は agent: のモデルが優先される点も押さえておきたい。

effort: の対応状況は以下である。

環境変数 CLAUDE_CODE_EFFORT_LEVEL がフロントマターより優先されるため、CI やチーム共有設定で統一したい場合に便利である。

スキルの命名規則

name フィールドには以下のルールがある。

• 最大 64 文字、小文字・数字・ハイフンのみ
• 動名詞形 推奨（例: analyzing-spreadsheets）
• スキルが提供する 活動・機能 を明確に表す名前にする
• ディレクトリ名と name 値は一致させる（agentskills.io 仕様準拠）

description 設計の 3 原則

description はスキルの自動発動を左右する最重要フィールドである。3 つの原則を押さえる。

1. フロントロード: 重要情報を先頭に配置する
2. 具体性: 抽象語を避け、動詞＋対象で書く
3. やや積極的に書く: 控えめに書くと発動漏れ（undertriggering）が起きる。Use when the user asks to X のように発動条件を明示する

上限は 1024 文字だが、実運用では 250 字以内 に収め、先頭 1〜2 文で発動条件を示すのが発動率最大化のコツである。

良い例と悪い例

copy❌ 悪い例: データ処理を手伝う
✅ 良い例: Excel スプレッドシートを分析しピボットテーブルを作成。
          ユーザーが .xlsx 解析を依頼したら使用。

description が発動しない 4 つの原因

「書いたのに自動起動しない」という相談は多い。主因は以下の 4 つである。

1. 自然言語マッチのみ: Claude はコードレベルで意図検出しない。自然言語で発動条件を書く
2. 類似スキル間の競合: 似た description があるとモデルがどちらを呼ぶか迷う
3. キーワード不足: ファイル名・操作名などの具体語がないと自然言語マッチが弱い
4. 曖昧な記述: 「helps with data」のような vague 表現は低トリガー率

スキルのディレクトリ構造とネスト

スキル自体は 1 階層フラット で構成する。

copymy-skill/
├── SKILL.md      ← スキル本体
├── references/
└── scripts/
    └── (子 SKILL.md は仕様外)

「1 スキル = 1 ディレクトリ + 1 SKILL.md」が原則であり、SKILL.md のネストは agentskills.io 仕様外である。

一方、機能グループ化 は .claude/skills/ 直下で可能である。

copy.claude/skills/
├── docs-skills/
│   ├── explain-code/SKILL.md
│   └── summarize-pr/SKILL.md
└── ops-skills/
    ├── deploy-check/SKILL.md
    └── release-note/SKILL.md

Claude Code の "Automatic discovery from nested directories" により、中間ディレクトリ経由でも自動検出される。

フロントマター応用

allowed-tools で最小権限化

スキルがアクティブな間、Claude が使える ツールを限定 できる。

copy---
name: code-audit
description: Read-only code audit.
allowed-tools:
  - Read
  - Glob
  - Grep
---

これで「ファイルを探索できるが変更はできない」読み取り専用モードが作れる。監査／レビュー／情報収集／PR 要約など、副作用を出したくない用途に向く。

context: fork でサブエージェント実行

重い処理をメインコンテキストから切り離すなら context: fork を使う。

copy---
name: deep-analysis
context: fork
agent: Explore
---

挙動は以下の通りである。

1. 新しい分離コンテキストが生成される
2. スキル内容がサブエージェントのプロンプトになる
3. agent: が実行環境（モデル・ツール・権限）を決定
4. 結果が要約されメイン会話に返却される

agent: の選択肢は以下である。

サブエージェント側から skills: でプリロード

逆方向の連携として、サブエージェント定義の frontmatter でスキルをプリロードできる。

copy---
name: security-reviewer
description: Performs security review
tools: Read, Grep, Glob
skills:
  - example-skills:code-audit
  - security-guidelines
---

あなたはセキュリティレビュー専門エージェント。
OWASP Top 10 を念頭に、与えられた PR を評価せよ。

サブエージェント起動時に指定スキルが自動注入される。なお、プラグイン経由のサブエージェントでは hooks / mcpServers / permissionMode は 無効化 される（セキュリティ制約）。

サポートファイル分割と Progressive Disclosure

3 層の分割目安

• L1 フロントマター: 常時メモリ常駐（name + description）
• L2 SKILL.md 本文: スキル発動時にロード
• L3 references/ / scripts/ / assets/: 必要時のみリンク経由で読込
• SKILL.md 500 行超 で L3 へ切り出し

ディレクトリ構造の例を示す。

copyskill-name/
├── SKILL.md       # エントリポイント（L2）
├── FORMS.md       # フォーム定義（L3）
├── REFERENCE.md   # 参照資料（L3）
└── scripts/
    └── validate.py

SKILL.md からの参照例

copy## 詳細な XML 操作は [REFERENCE.md](./REFERENCE.md) を参照
## フォーム入力仕様は [FORMS.md](./FORMS.md) を参照
## 検証スクリプト: `python scripts/validate.py <dir>`

Claude は 読み込むタイミング が分かるよう、SKILL.md 本文内で明示的にリンクを張る必要がある。リンクされていない L3 ファイルは発動時に参照されない。

バリデーションループパターン

フィードバックループは出力品質を大幅に向上させる。ドキュメントより「スクリプトを書く」のが定石である。

copy## ドキュメント編集プロセス

1. word/document.xml に編集を加える
2. すぐに検証: python ooxml/scripts/validate.py unpacked_dir/
3. 検証が失敗した場合:
   - エラーメッセージを注意深く確認
   - XML の問題を修正
   - 検証を再度実行
4. 検証が成功した場合のみ続行
5. 再構築: python ooxml/scripts/pack.py unpacked_dir/ output.docx
6. 出力ドキュメントをテスト

スクリプトは決定論的で時間を節約する。そしてエラーメッセージだけがコンテキストに入り、スクリプト本体は非ロード のまま処理が進む。

スキル記述のベストプラクティス

時間に敏感な情報を避ける

「2026 年現在」「今月のレート」等は陳腐化の温床である。動的取得にするか、日付付きで更新周期を明記する。

一貫した用語

「ユーザー」「顧客」「クライアント」を混在させない。表記揺れは精度低下 の原因になる。

ドメイン別で構造化

良い例は reference/finance.md reference/sales.md のようにドメインで分ける。悪い例は docs/file1.md docs/file2.md のように意味のないファイル名にすることである。

スキル設計の 3 パターン

• テンプレートパターン: 定型フォーマットに値を流し込む。メール・レポート・議事録作成に有効
• 例パターン: Few-shot の要領で「入力 → 出力」の実例を複数見せる。コーディング規約の徹底に有効
• 条件付きワークフロー: 「X なら A、Y なら B」の分岐を明示。PR レビュー・承認フローに有効

実践 TIPS

動的値の文字列置換変数 $ARGUMENTS

スキル呼び出し時の 全引数をそのまま SKILL.md 本文に展開 する置換変数である。

copy---
name: generate-pr-description
description: Generates PR from ticket. Use with a ticket ID argument.
---

対象チケット: $ARGUMENTS

上記チケットから PR description を生成せよ。
形式は conventional commits に従うこと。

/generate-pr-description PROJ-1234 で呼び出すと、$ARGUMENTS が PROJ-1234 に置換されて Claude に渡される。

MCP ツール参照の明示化

description や SKILL.md 本文で ServerName:tool_name 形式で明示参照すると、モデルが MCP ツール呼び出しを自然言語から推論する精度が向上する。

copy## PR レビュー時の処理
- GitHub:create_issue ツールを使用して問題を作成せよ
- Linear:search_issues で関連チケットを検索
- Slack:post_message でレビュー結果を #review に投稿

プレフィックス ServerName がフックとなり、モデルが対応する MCP ツールを正確に選択する。サーバー名は大文字・小文字を定義と揃えること。

シェル事前実行と拡張思考

バッククォート + ! の構文で、スキル内容が Claude に送られる 前に シェルコマンドを実行し、出力でプレースホルダを置換できる。

copy## Pull request context
- PR diff: !`gh pr diff`
- Files: !`gh pr diff --name-only`

Claude は実データ入りのプロンプトを受け取る。無効化するには disableSkillShellExecution: true（v2.1.91〜）を設定する。

また、スキル本文のどこかに ultrathink の単語 を含めると拡張思考モードが有効化される。慎重な設計レビューなどで活用できる。

copyこのレビューは慎重に。ultrathink で設計意図の再構築から始めること。

アンチパターン全解説

記述・構造編

Windows スタイルパス: scripts\helper.py ではなく scripts/helper.py で統一する。Windows でも POSIX パスが正解である。

選択肢を提供しすぎ: 「pypdf または pdfplumber または PyMuPDF または…」のように並べない。1 つ決めて書く。Claude に判断を委ねすぎると精度が落ちる。

エラーハンドリング欠如: 「エラーは適宜処理」と Claude に任せず、スクリプト側で明示的に記述し、失敗時のフォールバックを固定化する。

ネイティブ機能の再実装: 「クリーンなコードを書け」「エラー処理せよ」など Claude が既に知っていることは書かない。スキル固有の知識・手順だけを書く。

スコープが広すぎる単一スキル: 1 スキルで「コードレビュー + デプロイ + リリースノート生成」を全部やらせない。1 スキル = 1 目的。

500 行超を分割しない: SKILL.md に全部書き込まず、L3 リソースへ積極的に切り出す。

発動・運用編

description が抽象的: 「コードを改善するスキル」ではなく「重複ロジックを検出し、共通関数に抽出。git diff 後の PR 提出前に使用」のように 何を・いつ を具体フレーズで書く。

MUST の多用: 「MUST do X」「MUST NOT Y」を全項目に連呼しない。例外処理の柔軟性を残し、prefer や if ... then ... を使い分ける。

時間に敏感な情報をハードコード: 「2026 年 4 月現在、API バージョンは v3」のように書かない。動的取得か、日付と更新周期を明記する。

バリデーションループ省略: 出力の正しさを Claude の目視にのみ依存しない。検証スクリプトを書き、失敗時は自動ループで修正→再検証する。

最小権限違反: allowed-tools 未指定で Bash / Write まで暗黙許可しない。監査・読み取り系スキルは Read / Glob / Grep のみに絞る。

NAMESPACE 衝突: Enterprise / Personal / Project / Plugin に同名スキルを置かない。優先順位を理解し、配置前に /skills で既存確認する。

「半年後の自分が読んで意味が通るか」を書いた直後にチェックするとよい。時間依存・文脈依存の記述が最大の技術的負債源である。

【必須】セキュリティと ZDR データ保持

悪意あるスキルの実態

Skills は 信頼できるソースからのみ使用 するのが鉄則である。自作または Anthropic 取得のもの以外は慎重に扱う。外部 URL からデータを取得するスキルは特に危険で、取得コンテンツに悪意指示が混入し得る。

2026 年 2 月の Snyk 監査では、3,984 スキル中の以下の数値が報告されている。

代表的な攻撃ベクタは次の通りである。

• プロンプトインジェクション: 記載目的と異なるツール呼び出し指示
• マルウェア: スクリプトに難読化コード
• 外部 URL 依存: 時間経過で外部リソースが侵害される
• 信頼済みスキルの悪用: 更新時の改竄

ZDR: 保持対象と保持期間

ここが本稿で最も重要なセクションである。

Agent Skills は ZDR（Zero Data Retention）契約の対象外 である。公式 API Docs に明記されている。

"Agent Skills is not covered by ZDR arrangements." — Anthropic Docs

保持対象となるのは以下である。

• SKILL.md 本体（name / description 含む）
• scripts/ 配下のスクリプト
• references/ 参照ファイル
• 実行時の入出力ログ

保持期間は以下である。

• 最大 30 日（Code Execution 基盤経由）
• ポリシー違反検出時は 最大 2 年
• HIPAA 適格でもない

実務的対策と利用シーン別判断

実務では以下の対策を徹底する。

• 機密情報を SKILL.md に 直書きしない（API キー・顧客データ・社外秘ロジック）
• 値は 環境変数や Vault 経由 で注入する
• ZDR 契約済み企業でも、Skills 利用時は別扱いになる
• MCP Connector も同様に ZDR 対象外である点に注意

利用シーン別の判断基準は以下である。

• 個人利用・発信: 気にしなくて OK
• 業務利用: SKILL.md を社外秘扱いにしない、チームで共有可能な前提で書く
• 機密ロジックが必須な場合: 別リポジトリに隔離し、スキルからは CLI / API 経由で呼び出す

まとめ

Claude Agent Skills 実践編の要点を振り返る。

• 作成: skill-creator で最小構成から開始し、evals.json で効果測定する
• フロントマター: description は 1024 字上限だが実運用は 250 字以内で具体フレーズを書く。副作用系は disable-model-invocation: true
• 応用: allowed-tools で最小権限、重処理は context: fork でサブエージェントに委譲
• プラクティス: 500 行超は Progressive Disclosure で分割、バリデーションループで信頼性を確保
• TIPS: $ARGUMENTS で動的注入、バッククォート + ! でシェル事前実行、ultrathink で拡張思考
• アンチパターン回避: 1 スキル 1 目的、時間依存・NAMESPACE 衝突・最小権限違反に注意
• セキュリティ: Agent Skills は ZDR 対象外。機密は SKILL.md に書かない、信頼できるソースのみを使う