Agent Skills上級テクニック【references・scripts・templatesの活用】

基本的なSKILL.mdの書き方はマスターしたけど、「もっと複雑なことがしたい」と思っていませんか？

Agent Skillsは、SKILL.md単体だけでなく、references/、scripts/、templates/などのディレクトリを活用することで、より高度な機能を実現できます。

この記事では、上級者向けのスキル作成テクニックを解説します。

スキルの拡張構造

基本構造に加えて、以下のディレクトリを追加できます：

Copymy-advanced-skill/
├── SKILL.md              # 必須：メインの指示
├── references/           # 詳細ドキュメント
│   ├── coding-standards.md
│   └── security-checklist.md
├── scripts/              # 実行可能スクリプト
│   └── lint-check.sh
├── templates/            # 出力テンプレート
│   └── pr-description.md
└── assets/               # その他のリソース
    └── config.json

references/：詳細ドキュメントの分割

なぜ分割するか

SKILL.mdが長くなりすぎると、以下の問題が発生します：

• コンテキストウィンドウを圧迫
• 読み込み時間が増加
• メンテナンスが困難

推奨サイズ（SKILL.md本体：5,000トークン以下）を超える場合は、詳細をreferences/に分割します。

分割の例

SKILL.md（簡潔に）：

Copy---
name: code-review
description: チームのコーディング規約に沿ってPRをレビューする
---

## 概要

PRのコードをレビューし、チームの規約に沿っているか確認します。

## 参照ドキュメント

詳細なルールは以下を参照：
- `references/coding-standards.md` - コーディング規約
- `references/security-checklist.md` - セキュリティチェックリスト

references/coding-standards.md（詳細）：

Copy# コーディング規約

## 命名規則

- 変数：camelCase
- 定数：UPPER_SNAKE_CASE
- クラス：PascalCase
- ファイル：kebab-case

## インデント

- スペース2つ
- タブは使用禁止

[... 詳細なルールが続く ...]

Progressive Disclosureの仕組み

AIはタスクに応じて必要なファイルだけを読み込みます：

1. 最初はSKILL.mdのnameとdescriptionのみ
2. スキルが呼び出されたらSKILL.md全体を読み込み
3. 必要に応じてreferences/のファイルを読み込み

これにより、大量のドキュメントがあってもパフォーマンスを維持できます。

scripts/：自動化スクリプト

使用例

scripts/lint-check.sh：

Copy#!/bin/bash
# コードのlintチェックを実行
# 使用法：このスクリプトはスキル実行時に自動で呼び出されます

echo "Running lint check..."
npm run lint --silent

if [ $? -eq 0 ]; then
    echo "✓ Lint check passed"
else
    echo "✗ Lint errors found"
    exit 1
fi

SKILL.mdでの参照：

Copy## 実行手順

1. まず `scripts/lint-check.sh` を実行してlintエラーがないか確認
2. エラーがあれば修正を提案
3. エラーがなければレビューを開始

注意点

• ツール依存：scripts/の実行はClaude Codeでは動作しますが、他のツールでは動かない場合があります
• セキュリティ：外部から取得したスクリプトは必ず内容を確認してから使用
• べき等性：何度実行しても同じ結果になるように設計

templates/：出力フォーマットの統一

使用例

templates/pr-description.md：

Copy## 概要

<!-- 変更の概要を1-2文で -->

## 変更内容

- [ ] 機能追加
- [ ] バグ修正
- [ ] リファクタリング
- [ ] ドキュメント更新

## 詳細

### 変更点

<!-- 具体的な変更内容 -->

### テスト

<!-- テスト方法 -->

## 関連Issue

<!-- #123 など -->

SKILL.mdでの使用：

Copy## 手順

1. 変更内容を分析
2. `templates/pr-description.md` のフォーマットに沿って説明文を生成
3. 適切な項目にチェックを入れる

メリット

• チーム全体でPRの形式が統一される
• 必要な情報の抜け漏れを防げる
• レビュアーにとって読みやすい

複数ファイルの連携

高度なスキルの例

Copysecurity-audit/
├── SKILL.md
├── references/
│   ├── owasp-top-10.md
│   ├── company-policy.md
│   └── exception-list.md
├── scripts/
│   ├── dependency-check.sh
│   └── secret-scan.sh
└── templates/
    └── audit-report.md

SKILL.md：

Copy---
name: security-audit
description: コードのセキュリティ監査を実施し、OWASP Top 10と社内ポリシーに基づいてレポートを生成
---

## 監査手順

### 1. 自動チェック

まず以下のスクリプトを実行：
- `scripts/dependency-check.sh` - 依存パッケージの脆弱性チェック
- `scripts/secret-scan.sh` - シークレットの漏洩チェック

### 2. 手動レビュー

以下のドキュメントに基づいてコードをレビュー：
- `references/owasp-top-10.md` - OWASP Top 10の観点
- `references/company-policy.md` - 社内セキュリティポリシー

例外リストは `references/exception-list.md` を参照。

### 3. レポート生成

`templates/audit-report.md` のフォーマットで監査レポートを生成。

ベストプラクティス

ファイルサイズの目安

分割の判断基準

以下の場合は分割を検討：

• SKILL.mdが500行を超えた
• 特定の参照情報が頻繁に更新される
• 複数のスキルで同じ情報を参照したい

互換性を考慮

他のツールでも使いたい場合は、scripts/への依存を最小限に：

Copy## 注意

このスキルは `scripts/lint-check.sh` を使用しますが、
スクリプトが実行できない環境では、手動で `npm run lint` を実行してください。

まとめ

Agent Skillsの拡張構造を活用することで、より高度なワークフローを実現できます：

• references/：詳細ドキュメントを分割してSKILL.mdを軽量に
• scripts/：自動化スクリプトで効率化
• templates/：出力フォーマットを統一

まずは小さく始めて、必要に応じて拡張していくのがおすすめです。

関連記事

• 自分でスキルを作る方法 - 基本的なスキル作成
• チームでスキルを共有する方法 - 高度なスキルをチームで活用
• スキルのセキュリティベストプラクティス - scripts/を安全に使う
• 開発効率を上げる7つのTips - スキル活用のコツ