Skills スクリプト拡張

SKILL.md に指示を書くだけでなく、scripts ディレクトリを通じてスキルに実行可能コードを追加することもできます。

このセクションでは、スクリプトを使ってスキルの機能を拡張する方法を学びます。


なぜスクリプトを使うのか

スクリプトを使うと以下のことができます:

  • 複雑なロジックをカプセル化し、SKILL.md に大量のコードを書くのを避ける
  • テスト済みの信頼できる実装を提供する
  • エージェントが同じツールや関数を再利用できるようにする
  • より複雑な入出力操作を処理する

ヒント:複数回の実行でエージェントが同じロジックを繰り返し実装していることに気づいたら、それがスクリプトを作成する良いタイミングです。


スクリプトのディレクトリ構造

スクリプトはスキルディレクトリの scripts/ サブディレクトリに置くべきです:

ディレクトリ構造

my-skill/
├── SKILL.md
└── scripts/
    ├── script1.py
    ├── script2.sh
    └── helper.js

スクリプト作成規範

1. 自己完結性

スクリプトは可能な限り自己完結であるか、依存関係を明確に記録する必要があります。

自己完結スクリプトの例

#!/usr/bin/env python3
"""
PDFテキスト抽出スクリプト

依存関係:pip install pdfplumber
実行:python scripts/extract_pdf.py input.pdf
"""


import sys
import pdfplumber

def extract_text_from_pdf(pdf_path):
    """PDFファイルからテキストを抽出する"""
    with pdfplumber.open(pdf_path) as pdf:
        text = ""
        for page in pdf.pages:
            text += page.extract_text() or ""
    return text

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("使い方: python extract_pdf.py <pdfファイル>")
        sys.exit(1)

    pdf_path = sys.argv[1]
    text = extract_text_from_pdf(pdf_path)
    print(text)

2. 明確なエラーハンドリング

スクリプトは、エージェントが何が問題かを理解できるように、有用なエラーメッセージを提供すべきです。

エラーハンドリングの例

import sys

def main():
    if len(sys.argv) < 2:
        print("エラー:必須パラメータが不足しています", file=sys.stderr)
        print("使い方: python script.py <入力ファイル> [出力ファイル]", file=sys.stderr)
        sys.exit(1)

    input_file = sys.argv[1]

    try:
        # メインロジックを実行
        process_file(input_file)
    except FileNotFoundError:
        print(f"エラー:ファイル {input_file} が見つかりません", file=sys.stderr)
        sys.exit(1)
    except PermissionError:
        print(f"エラー:ファイル {input_file} を読み取る権限がありません", file=sys.stderr)
        sys.exit(1)
    except Exception as e:
        print(f"エラー:ファイル処理中に不明なエラーが発生しました: {e}", file=sys.stderr)
        sys.exit(1)

if __name__ == "__main__":
    main()

3. エッジケースの処理

スクリプトはクラッシュせず、さまざまなエッジケースを優雅に処理すべきです。

エッジケース処理の例

def validate_input(text):
    """入力が有効かどうかを検証する"""
    if not text:
        return False, "入力は空にできません"

    if len(text) > 10000:
        return False, "入力長が制限を超えています(最大10000文字)"

    return True, ""

# 検証を使用
is_valid, error_msg = validate_input(user_input)
if not is_valid:
    print(f"検証失敗: {error_msg}")
    sys.exit(1)

SKILL.md でスクリプトを参照する

スキルがスクリプトを実行する必要がある場合、SKILL.md でその呼び出し方を説明します。

スクリプトの参照:

## PDF 文本提取

使用脚本提取 PDF 中的文本:

```bash
python scripts/extract_pdf.py input.pdf
```

脚本会从 input.pdf 提取所有文本并输出到标准输出。

如果需要将结果保存到文件:

```bash
python scripts/extract_pdf.py input.pdf > output.txt
```

注意:スクリプトを参照する際は、スキルのルートディレクトリからの相対パスを使用します。


サポートされるスクリプト言語

サポートされるスクリプト言語は、使用するエージェント実装によって異なります。一般的なオプションは次のとおりです:

言語 説明
Python 最も一般的な選択肢で、強力かつ書きやすい
Bash システム操作やコマンドラインツールに適している
JavaScript Web関連のタスクに適している

ヒント:スクリプト言語を選ぶときは、対象ユーザーの実行環境を考慮してください。不明な場合は、Python が最も安全な選択です。


完全な例:PDF処理スキル

SKILL.md とスクリプトを組み合わせる方法を示す完全な例を見てみましょう:

スキル構造

pdf-tool/
├── SKILL.md
└── scripts/
    ├── extract.py
    ├── fill_form.py
    └── merge.py

SKILL.md の内容:

---
name: pdf-tool
description: 处理 PDF 文件,包括提取文本、填写表单、合并文件。使用场景:处理 PDF、提取文本、填写表单、合并 PDF。
---

## 提取 PDF 文本

从 PDF 文件中提取文本内容:

```bash
python scripts/extract.py input.pdf
```

输出是提取的纯文本内容。

## 填写 PDF 表单

使用 JSON 数据填写 PDF 表单:

```bash
python scripts/fill_form.py input.pdf data.json output.pdf
```

data.json 格式:
```json
{
  "field_name": "字段值",
  "another_field": "另一个值"
}
```

## 合并 PDF

将多个 PDF 文件合并为一个:

```bash
python scripts/merge.py output.pdf input1.pdf input2.pdf input3.pdf
```

## 依赖安装

需要安装 pdfplumber 和 PyPDF2:

```bash
pip install pdfplumber PyPDF2
```

2つの使用方法

Skill でコードを使用する方法は2つあります:

方法 適用シーン scripts/ ディレクトリが必要かどうか
一回限りのコマンド 既存のツールを呼び出すだけで、カスタムロジックは不要 不要
自己完結スクリプト 再利用が必要な複雑なロジック 必要

一回限りのコマンド

既存のパッケージマネージャツールで要件を満たせる場合は、SKILL.md の指示に直接記述して参照すればよく、scripts/ ディレクトリを作成する必要はありません。

以下は各言語エコシステムの一般的な実行方法です:

uvx(Python)

uvx は uv に付属のツール実行コマンドで、分離された環境で Python パッケージを実行します。また、キャッシュが積極的で、繰り返し実行はほぼ瞬時に完了します。

例

# 指定バージョンの ruff を実行してコードをチェック
uvx ruff@0.8.0 check .

# 指定バージョンの black を実行してコードをフォーマット
uvx black@24.10.0 .

pipx(Python)

pipx は uvx の成熟した代替手段で、システムパッケージマネージャでインストールできます(例:brew install pipx)。

例

# 指定バージョンの black を実行
pipx run 'black==24.10.0' .

# 指定バージョンの ruff を実行
pipx run 'ruff@0.8.0' check .

npx(Node.js)

npx は npm に付属しており、必要に応じて npm パッケージをダウンロードして実行します。

例

# ESLint を実行してチェック
npx eslint@9 --fix .

# Vite を使用してプロジェクトを作成
npx create-vite@6 my-app

go run(Go)

Go に付属のツール実行コマンドで、リモートパッケージを直接コンパイルして実行します。

例

# goimports を実行してインポートをフォーマット
go run golang.org/x/tools/cmd/goimports@v0.28.0 .

# golangci-lint を実行してチェック
go run github.com/golangci/golangci-lint/cmd/golangci-lint@v1.62.0 run

一回限りのコマンドを作成する際のアドバイス:バージョン番号を固定する(例:npx eslint@9.0.0)ことで動作の一貫性を確保します。SKILL.md で前提条件(「Node.js 18+ が必要」など)を宣言します。コマンドが複雑になった場合は、scripts/ ディレクトリに抽出する必要があります。


SKILL.md でスクリプトを参照する

Skill ディレクトリのルートから始まる相対パスを使用して、パッケージ化されたファイルを参照します。

Agent はこれらのパスを自動的に解決するため、絶対パスを使用する必要はありません。

まず SKILL.md で利用可能なスクリプトを一覧表示します:

例

## 利用可能なスクリプト

- **`scripts/validate.sh`** — 設定ファイルの検証
- **`scripts/process.py`** — 入力データの処理
- **`scripts/report.py`** — 分析レポートの生成

次に、操作手順でそれらを参照します:

例

## 操作手順

1. 検証スクリプトを実行:
   ```bash
   bash scripts/validate.sh "$INPUT_FILE"
   ```

2. データを処理:
   ```bash
   python3 scripts/process.py --input results.json
   ```

スクリプトの実行パスは Skill ディレクトリのルートを基準とします。Agent は Skill ディレクトリ内からコマンドを実行するためです。これは references/*.md などの補助ファイルにも同様に適用されます。


自己完結スクリプト

再利用可能なロジックが必要な場合は、スクリプトをscripts/ディレクトリ内にパッケージ化し、スクリプト内で依存関係を宣言できます。

Agent は追加のインストール手順なしで、1つのコマンドだけで実行できます。

Python 自己完結スクリプト(PEP 723)

PEP 723 は、Python スクリプト内で依存関係を宣言するための標準形式を定義しています。

マーカーを使用して# ///TOML 形式の依存関係宣言を囲みます:

例:Python 自己完結スクリプト

# /// script
# dependencies = [
#   "beautifulsoup4",
# ]
# ///

from bs4 import BeautifulSoup

# サンプル HTML コンテンツ
html = '<html><body><h1>Welcome</h1><p class="info">サンプル 测试</p></body></html>'

# BeautifulSoup を使用して HTML を解析
soup = BeautifulSoup(html, "html.parser")

# class="info" の段落テキストを抽出
info_text = soup.select_one("p.info").get_text()
print(info_text)

実行方法:

例

# uv を使用して実行(推奨)
uv run scripts/extract.py

# pipx を使用して実行
pipx run scripts/extract.py
サンプル 测试

Deno 自己完結スクリプト

Deno はnpm:とjsr:import 指定子で自己完結を実現します:

例:Deno 自己完結スクリプト

#!/usr/bin/env -S deno run

import * as cheerio from "npm:cheerio@1.0.0";

const html = `<html><body><h1>Welcome</h1><p class="info">サンプル 测试</p></body></html>`;
const $ = cheerio.load(html);
console.log($("p.info").text());

例

deno run scripts/extract.ts

Bun 自己完結スクリプト

Bun はnode_modulesディレクトリがない場合、欠落しているパッケージを自動的にインストールします:

例:Bun 自己完結スクリプト

#!/usr/bin/env bun

import * as cheerio from "cheerio@1.0.0";

const html = `<html><body><h1>Welcome</h1><p class="info">サンプル 测试</p></body></html>`;
const $ = cheerio.load(html);
console.log($("p.info").text());

例

bun run scripts/extract.ts

Ruby 自己完結スクリプト

Ruby はbundler/inlineスクリプト内で gem の依存関係を宣言します:

例:Ruby 自己完結スクリプト

require 'bundler/inline'

gemfile do
  source 'https://rubygems.org'
  gem 'nokogiri'
end

html = '<html><body><h1>Welcome</h1><p class="info">サンプル 测试</p></body></html>'
doc = Nokogiri::HTML(html)
puts doc.at_css('p.info').text

例

ruby scripts/extract.rb

Agent向けスクリプト設計のポイント

Agent は stdout と stderr を読み取って次のアクションを決定するため、スクリプトの設計では Agent の使用特性を考慮する必要があります。

対話型プロンプトを避ける

これは必須要件です。Agent は非対話型シェルで実行されるため、TTY プロンプト、パスワードダイアログ、確認メニューに応答できません。

すべての入力は、コマンドライン引数、環境変数、または stdin を介して渡す必要があります。

例:悪い例 vs 良い例

# 悪い例:入力待ちで停止してしまう
$ python scripts/deploy.py
Target environment: _

# 良い例:明確なエラーメッセージとガイダンス
$ python scripts/deploy.py
Error: --env is required. Options: development, staging, production.
Usage: python scripts/deploy.py --env staging --tag v1.2.3

--help ドキュメントを提供する

--help出力は、Agent がスクリプトのインターフェースを理解するための主要な手段です。

簡単な説明、利用可能なパラメータ、使用例を含めます:

例:適切な --help 出力

Usage: scripts/process.py [OPTIONS] INPUT_FILE

入力データを処理してサマリーレポートを生成します。

Options:
  --formatFORMAT 出力形式: json, csv, table(デフォルト: json)
  --outputFILE 出力を stdout ではなくファイルに書き込む
  --verbose進行状況情報を stderr に出力する

Examples:
  scripts/process.py data.csv
  scripts/process.py --format csv --output report.csv data.csv

有用なエラーメッセージを書く

Agent はエラーメッセージを確認してそれに基づき戦略を調整します。情報が具体的であればあるほど、Agent は自己修正しやすくなります。

例

# 良くないエラーメッセージ
Error: invalid input

# 良いエラーメッセージ
Error: --format must be one of: json, csv, table.
       Received: "xml"

構造化出力を使用する

自由テキストではなく、JSON、CSV、TSV などの構造化形式での出力を優先します。

構造化形式は Agent と標準ツール(jq、cut、awk)の両方が利用でき、組み合わせて使用しやすくなります。

例

# 非推奨:整列テキストはプログラムでの解析が難しい
NAME          STATUS    CREATED
my-service    running   2025-01-15

# 推奨:JSON 形式はフィールドの境界が明確
{"name": "my-service", "status": "running", "created": "2025-01-15"}

構造化データは stdout に、進行状況メッセージと診断情報は stderr に出力します。これにより、Agent はクリーンで解析可能な出力を取得でき、必要に応じて診断情報も確認できます。


その他のスクリプト設計のアドバイス

アドバイス 説明
冪等性 Agent はコマンドを再試行する可能性があります。「存在しなければ作成」は、「作成して重複時にエラーを返す」よりも安全です
入力の制約 ユーザーの意図を推測するのではなく、明確なエラーで曖昧な入力を拒否する
Dry-run のサポート 破壊的または状態を変更する操作には、--dry-runフラグを提供し、Agent が操作をプレビューできるようにする
意味のある終了コード 失敗の種類に応じて異なる終了コードを使用する(見つからない、無効なパラメータ、認証失敗など)
予測可能な出力サイズ デフォルトではサマリーを出力し、--offsetなどのパラメータを提供して、Agent が必要に応じて詳細情報を取得できるようにする
安全なデフォルト値 破壊的な操作には明示的な確認フラグを要求する(--confirm、--force)

完全なSkillスクリプトの例

以下は、スクリプトを含む完全な Skill ディレクトリ構造です:

例

csv-analyzer/
├── SKILL.md              # メインの指示ファイル
├── scripts/
│   ├── overview.py       # データ概要スクリプト
│   ├── summary.py        # 統計サマリースクリプト
│   └── validate.py       # データ検証スクリプト
├── references/
│   └── api-errors.md     # API エラーリファレンス
└── assets/
    └── report-template.md  # レポートテンプレート

対応する SKILL.md の内容:

例

---
name: csv-analyzer
description: >
CSV および表形式のデータファイルを分析します。ユーザーが CSV、TSV、または Excel ファイルを持っており、
データの探索、変換、または可視化を行いたい場合に使用します。
---

# CSV データ分析

## 利用可能なスクリプト

- **`scripts/overview.py`** — データの概要を表示(行数、列名、型)
- **`scripts/summary.py`** — 統計サマリーを生成
- **`scripts/validate.py`** — データ品質を検証

## 操作手順

1. 最初に概要スクリプトを実行してデータ構造を把握します:
   ```bash
   uv run scripts/overview.py input.csv
   ```

2. 統計サマリーを生成します:
   ```bash
   uv run scripts/summary.py input.csv --output summary.json
   ```

3. データ品質を検証します:
   ```bash
   uv run scripts/validate.py input.csv
   ```

## 注意事項

- 大きなファイルは `--chunk-size` パラメータを使用してチャンク単位で処理します
- 中国語の CSV の場合は `--encoding gbk` パラメータを試してください

スクリプトの配布と依存関係

スクリプトに外部依存関係が必要な場合、いくつかの選択肢があります:

1. SKILL.md で依存関係を説明する

最も簡単な方法は、必要な依存関係を SKILL.md に記録することです。

2. 仮想環境を使用する

複雑なプロジェクトの場合は、仮想環境を作成できます。

3. Docker を使用する

完全な実行環境が必要な場合は、Docker コンテナを使用できます。

注意:スクリプトがターゲット環境で実行できることを確認してください。スクリプトを作成する前に、対象ユーザーの実行環境を把握してください。


まとめ

このセクションでは、スクリプトを使用してスキルの機能を拡張する方法を学びました:

  • スクリプトは scripts/ ディレクトリに配置する
  • スクリプトは自己完結型で、明確なエラーハンドリングを備えるべき
  • SKILL.md でスクリプトを参照する場合は相対パスを使用する
  • スクリプトがターゲット環境で実行できることを確認する
その他の拡張