Skills デザインパターンとベストプラクティス

多数の実践からまとめられた Skill デザインパターンは、新しい要件に直面したときに迅速で合理的な判断を下すのに役立ちます。

この記事では、最もよく使われる7つのデザインパターンとその適用シーンをまとめています。


パターン1:単一責任 Skill

各 Skill は一つのことだけを行い、その一つのことをきちんとやり遂げます。

機能がより焦点を絞られるほど、description はより正確になり、トリガー精度が高くなり、メンテナンスも容易になります。

やり方例
正しい:単一責任pdf-to-text(テキスト抽出のみを担当)
誤り:責任の混在pdf-tools(読み取り、変換、結合、透かし追加……すべてまとめて)

ある Skill の description が「何をしないか」を明確にするために長く書かなければならない場合、それは通常、担当する責任が多すぎることを意味し、分割すべきです。


パターン2:防御的入力チェック

Skill スクリプトのエントリーポイントで全ての入力検証を集中的に実行し、通過後にビジネスロジックへ進みます。

実例

# ファイルパス:scripts/defensive_entry.py
# パターン:防御的入力チェック——エントリーで集中的に検証し、通過後に許可

import sys
import os
import json

def validate(args) -> list:
    """すべての入力を集中的に検証し、エラーリストを返します(空リストはすべて通過を意味します)"""
    errors = []

    if not args.file:
        errors.append("パラメータ --file がありません")
    elif not os.path.exists(args.file):
        errors.append(f"ファイルが存在しません:{args.file}")
    elif os.path.getsize(args.file) == 0:
        errors.append("ファイルの内容が空です")

    if args.limit < 1:
        errors.append("--limit は 0 より大きい必要があります")

    return errors

def run(args):
    """ビジネスロジックのエントリーポイント。検証に合格した場合にのみ呼び出されます"""
    # 実際の処理を実行...
    return {"status": "success", "file": args.file}

if __name__ == "__main__":
    import argparse
    parser = argparse.ArgumentParser()
    parser.add_argument("--file",  required=False, default="")
    parser.add_argument("--limit", type=int, default=100)
    args = parser.parse_args()

    # 1. 集中的に検証
    errors = validate(args)
    if errors:
        result = {"status": "input_error", "errors": errors}
        print(json.dumps(result, ensure_ascii=False))
        sys.exit(1)

    # 2. 検証通過後にビジネスロジックを実行
    result = run(args)
    print(json.dumps(result, ensure_ascii=False))

パターン3:段階的出力

5秒以上かかる Skill については、ユーザーを沈黙の待機に直面させるのではなく、段階的に進捗を出力するべきです。

## 执行流程(渐进式输出示例)

### 步骤一:读取文件
运行读取脚本后,立即告知用户:
> 已读取文件:サンプル_data.csv(1,024 行,8 列)正在进行数据清洗...

### 步骤二:数据清洗
清洗完成后,告知用户:
> 数据清洗完成:删除重复行 3 条,空值填充 12 处。正在生成报告...

### 步骤三:生成报告
报告生成后,展示下载链接并说明内容:
> 报告已生成,包含统计摘要和数据质量评估。

パターン4:冪等操作

Skill の実行結果は冪等であるべきです。同じ入力であれば、何回実行しても出力は一貫している必要があります。

非冪等操作(実行のたびに内容を追記するなど)は、ユーザーが再試行した際に混乱を引き起こします。

実例

# ファイルパス:scripts/idempotent_output.py
import os
from datetime import datetime

OUTPUT_DIR = "/mnt/user-data/outputs"

def get_output_path(base_name: str, suffix: str = ".xlsx") -> str:
    """
決定的な出力パスを生成する

冪等な方法:実行のたびに同名ファイルを上書きする(追記や新規ファイルの生成ではなく)
同じ入力が常に同じ出力ファイルに対応することを保証する
    """

    # 方法A:固定ファイル名(同じ入力は常に上書き)
    return os.path.join(OUTPUT_DIR, f"{base_name}_report{suffix}")

    # 方法B(タイムスタンプ):実行ごとに新しいファイルを生成(非冪等だが、履歴を保持)
    # ts = datetime.now().strftime("%Y%m%d_%H%M%S")
    # return os.path.join(OUTPUT_DIR, f"{base_name}_{ts}{suffix}")

パターン5:明確な終了シグナル

Skill の実行が完了したら、「完了シグナル」を明確に提示し、ユーザーにタスクが終了したことを知らせて、これ以上待つ必要がないようにするべきです。

## 任务完成后的输出规范

无论成功还是失败,最后一步必须输出一个明确的状态行:

成功时:
> 任务完成:报告已生成,共处理 1,024 行数据,耗时约 3 秒。

失败时:
> 任务中断:在"数据清洗"步骤遇到错误(原因:文件编码不是 UTF-8)。
> 建议:将文件另存为 UTF-8 格式后重新上传。

パターン6:バージョン互換性の宣言

SKILL.md の frontmatter で互換性のあるモデルバージョンを宣言し、サポートされていない環境で予期しない動作が発生するのを防ぎます。

---
name: data-analyzer
version: 1.2.0
description: 分析 CSV/Excel 数据,生成统计报告。
compatibility:
  claude_models:
    - claude-sonnet-4-20250514   # 经过验证的模型版本
    - claude-opus-4              # 同样支持
  python: ">=3.8"
  platforms:
    - linux    # Claude 计算机使用环境
---

パターン7:Fail Fast(フェイルファスト)

続行できないエラーを発見したら、すぐに停止して明確に報告し、エラーを抱えたまま実行を続けて無意味な出力を生成しないようにします。

実例

# ファイルパス:scripts/fail_fast.py
import sys
import json

def assert_condition(condition: bool, message: str, hint: str = ""):
    """条件を満たさない場合、すぐにエラーを出力して終了します(Fail Fast パターン)"""
    if not condition:
        result = {
            "status":  "error",
            "message": message,
            "hint":    hint
        }
        print(json.dumps(result, ensure_ascii=False))
        sys.exit(1)

# スクリプトの先頭で全ての事前チェックを集中的に実行
import os
file_path = sys.argv[1] if len(sys.argv) > 1 else ""

assert_condition(bool(file_path),
                 "ファイルパスのパラメータがありません",
                 "使用方法:python script.py <ファイルパス>")

assert_condition(os.path.exists(file_path),
                 f"ファイルが存在しません:{file_path}",
                 "パスが正しいか確認するか、ファイルをアップロードし直してください")

assert_condition(file_path.endswith(".csv"),
                 "ファイル形式がサポートされていません。.csv が必要です",
                 f"実際のファイル:{file_path}")

# すべてのチェックに合格したら、実際のロジックを実行
print(json.dumps({"status": "ok", "file": file_path}))

パターン早見表

パターン核心原則解決する問題
単一責任1つの Skill は一つのことだけを行うトリガーが不正確、保守が困難
防御的入力チェックエントリーで集中的に検証実行途中でようやくエラーになる
段階的出力段階的に進捗を報告ユーザーは実行中かどうか分からない
冪等操作同じ入力には同じ出力再試行すると結果が混乱する
明確な終了シグナル完了後に最終状態の通知を出すユーザーはタスクが完了したかどうか分からない
バージョン互換性の宣言サポートする実行環境を宣言環境が一致しない場合に動作が異常になる
Fail Fastエラーに遭遇したら即座に停止エラーを抱えたまま継続して無効な出力を生成する
その他の拡張