Skillsとツールチェーン統合

Skillsは外部ツールチェーンと統合することで、Claude単独では実行できないタスクを完了できます。

この記事では、Skill内でコマンドラインツール、システムツール、サードパーティライブラリを呼び出す方法を紹介し、完全な統合例を提供します。


Skillsが呼び出せるツールの種類

ツールの種類例呼び出し方法
システムコマンドls、cp、find、wcsubprocess.run()
言語ランタイムpython、node、bashsubprocess.run()
ドキュメント処理ツールpandoc、pdflatexsubprocess.run()
メディア処理ツールffmpeg、imagemagicksubprocess.run()
Pythonライブラリpandas、openpyxl、pypdfimport後に直接呼び出す
Node.jsツールprettier、eslintnpxで呼び出す

外部ツールを呼び出す前に、ツールが実行環境にインストールされていることを確認してください。Claudeサンドボックスには一般的なツール(python3、pip、node、npm)がプリインストールされていますが、pandoc、ffmpegなどは追加でインストールする必要があります。


スクリプト内で外部コマンドを呼び出す

Pythonのsubprocessモジュールは外部コマンドを呼び出す標準的な方法であり、統一してツール関数にカプセル化して再利用することをお勧めします。

例

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

def run_command(cmd: list, timeout: int = 60) -> dict:
    """
外部コマンドを実行し出力をキャプチャする

引数:
cmd: コマンドリスト、例:["pandoc", "--version"]
timeout: タイムアウト秒数、デフォルト60

戻り値:
success、stdout、stderr、returncode を含む辞書
    """

    try:
        result = subprocess.run(
            cmd,
            capture_output=True,   # stdoutとstderrを同時にキャプチャ
            text=True,             # バイトではなく文字列として返す
            timeout=timeout
        )
        return {
            "success":    result.returncode == 0,
            "returncode": result.returncode,
            "stdout":     result.stdout.strip(),
            "stderr":     result.stderr.strip()
        }
    except FileNotFoundError:
        return {
            "success":    False,
            "returncode": -1,
            "stdout":     "",
            "stderr":     f"コマンドが存在しません:{cmd
        }
    except subprocess.TimeoutExpired:
        return {
            "success":    False,
            "returncode": -1,
            "stdout":     "",
            "stderr":     f"コマンド実行がタイムアウトしました({timeout}秒超過)"
        }

# 例:pandocを使用してMarkdownをHTMLに変換
if __name__ == "__main__":
    result = run_command([
        "pandoc",
        "/mnt/user-data/uploads/readme.md",
        "-o", "/mnt/user-data/outputs/readme.html",
        "--standalone"
    ])
    if result["success"]:
        print("変換成功")
    else:
        print(f"変換失敗:{result['stderr']}")
        sys.exit(1)

ツールが利用可能かどうかを確認する

Skillの実行前に必要なツールがインストールされているか確認することで、タスクが途中で失敗する前に明確なメッセージを表示できます。

例

# ファイルパス:scripts/check_tools.py
import shutil
import sys

REQUIRED_TOOLS = [
    ("pandoc",  "sudo apt-get install pandoc"),
    ("ffmpeg",  "sudo apt-get install ffmpeg"),
    ("convert", "sudo apt-get install imagemagick"),
]

def check_tools(tools: list) -> bool:
    """ツールリストを確認し、Trueを返すとすべて準備完了"""
    all_ok = True
    for tool, install_cmd in tools:
        path = shutil.which(tool)   # PATH内でツールのパスを検索
        if path:
            print(f" インストール済み:{tool} → {path}")
        else:
            print(f" 未インストール:{tool} インストールコマンド:{install_cmd}")
            all_ok = False
    return all_ok

if __name__ == "__main__":
    print("ツールの依存関係を確認中...")
    if not check_tools(REQUIRED_TOOLS):
        print("\n不足しているツールを先にインストールしてください。")
        sys.exit(1)
    print("\nすべてのツールが準備完了です。実行を続行します。")
检查工具依赖...
  已安装:pandoc → /usr/bin/pandoc
  未安装:ffmpeg  安装命令:sudo apt-get install ffmpeg
  未安装:convert  安装命令:sudo apt-get install imagemagick

请先安装缺少的工具。

SKILL.mdでツールの依存関係を宣言する

YAMLフロントマターのcompatibilityフィールドにすべての外部依存関係をリストアップし、ユーザーがSkillをインストールする前に何を準備する必要があるかを把握できるようにします。

---
name: doc-converter
description: >
  将文档在不同格式间转换,支持 Markdown、HTML、PDF、Word。
  当用户需要格式转换、导出文档时触发。
compatibility:
  tools:
    - pandoc >= 2.14   # 文档格式转换
    - python >= 3.8    # 运行辅助脚本
  python_packages:
    - pypdf >= 3.0     # PDF 处理
    - python-docx >= 1.0
---

Node.jsツールの統合

経由でnpxnpmパッケージ内のCLIツールを直接呼び出すことができ、グローバルインストールは不要です。

例

# ファイルパス:scripts/use_node_tool.py
import subprocess
import sys

def run_prettier(file_path: str) -> bool:
    """prettierを使用してコードファイルをフォーマット"""
    result = subprocess.run(
        ["npx", "--yes", "prettier", "--write", file_path],
        capture_output=True,
        text=True
    )
    if result.returncode == 0:
        print(f"フォーマット成功:{file_path}")
        return True
    print(f"フォーマット失敗:{result.stderr}")
    return False

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("使用方法:python use_node_tool.py <ファイルパス>")
        sys.exit(1)
    sys.exit(0 if run_prettier(sys.argv[1]) else 1)

npx --yes初回実行時にツールパッケージが自動的にダウンロードされるため、npmレジストリへのネットワーク接続が必要です。ネットワークが制限された環境では、事前にグローバルインストールしてください:npm install -g prettier。


ツール呼び出し結果の標準化処理

ツールによって出力形式は異なるため、Skill層で統一してカプセル化し、外部には一貫した構造のみを公開することをお勧めします。

処理方法適用シナリオ代表的なツール
stdoutをキャプチャツールが結果を標準出力に出力するpandoc、wc、cat
戻りコードを確認ツールは成功時に0、失敗時に0以外を返すほぼすべてのCLIツール
出力ファイルを読み取るツールが結果を指定ファイルに書き込むffmpeg、pandoc -o
JSON出力を解析ツールが--jsonパラメータをサポートeslint --format json

完全な統合例:MarkdownからPDFレポートへの変換

以下の例では、pandocとPythonスクリプトを組み合わせて、完全なMarkdown → PDF生成Skillスクリプトを実装します。

例

# ファイルパス:scripts/md_to_pdf.py
# 完全なワークフロー:ツール確認 → 入力検証 → pandoc呼び出し → 出力確認

import subprocess
import shutil
import sys
import os
import json
from datetime import datetime

def check_pandoc() -> bool:
    """pandocが利用可能かどうかを確認"""
    if not shutil.which("pandoc"):
        print("エラー:pandocが見つかりません。実行してください:sudo apt-get install pandoc")
        return False
    return True

def validate_input(md_path: str) -> bool:
    """入力されたMarkdownファイルを検証"""
    if not os.path.exists(md_path):
        print(f"エラー:ファイルが存在しません → {md_path}")
        return False
    if not md_path.lower().endswith(".md"):
        print(f"エラー:ファイルは.md形式である必要があります → {md_path}")
        return False
    return True

def convert_to_pdf(md_path: str, output_dir: str) -> dict:
    """pandocを呼び出してMarkdownをPDFに変換"""
    os.makedirs(output_dir, exist_ok=True)

    # タイムスタンプ付きの出力ファイル名を生成し、古いファイルの上書きを防ぐ
    base_name   = os.path.splitext(os.path.basename(md_path))[0]
    timestamp   = datetime.now().strftime("%Y%m%d_%H%M%S")
    output_path = os.path.join(output_dir, f"{base_name}_{timestamp}.pdf")

    result = subprocess.run(
        [
            "pandoc", md_path,
            "-o", output_path,
            "--pdf-engine=xelatex",      # 中国語をサポート
            "-V", "CJKmainfont=SimSun",  # 中国語フォント(環境に応じて調整)
            "-V", "geometry:margin=2cm"  # ページ余白
        ],
        capture_output=True,
        text=True,
        timeout=120
    )

    if result.returncode == 0 and os.path.exists(output_path):
        size_kb = os.path.getsize(output_path) // 1024
        return {
            "status":  "success",
            "output":  output_path,
            "size_kb": size_kb
        }
    return {
        "status": "error",
        "message": result.stderr or "pandocが出力ファイルを生成しませんでした"
    }

def main():
    if len(sys.argv) < 2:
        print("使用方法:python md_to_pdf.py <Markdownファイルパス>")
        sys.exit(1)

    md_path    = sys.argv[1]
    output_dir = "/mnt/user-data/outputs"

    # 段階的にチェックし、いずれかのステップが失敗したらすぐに終了
    if not check_pandoc():
        sys.exit(1)
    if not validate_input(md_path):
        sys.exit(1)

    print(f"変換中:{md_path}")
    result = convert_to_pdf(md_path, output_dir)
    print(json.dumps(result, ensure_ascii=False, indent=2))

    sys.exit(0 if result["status"] == "success" else 1)

if __name__ == "__main__":
    main()
正在转换:/mnt/user-data/uploads/サンプル_report.md
{
  "status": "success",
  "output": "/mnt/user-data/outputs/サンプル_report_20260518_102305.pdf",
  "size_kb": 248
}

SKILL.mdでこのスクリプトを呼び出す:

## 执行转换

获取用户上传的 .md 文件路径后,运行:

```bash
python scripts/md_to_pdf.py <文件路径>
```

解析 JSON 输出:
- status 为 "success":调用 present_files 展示 output 路径的文件
- status 为 "error":将 message 内容展示给用户,说明可能原因
その他の拡張