Skills の組み合わせと編成

単一のSkillは単一の問題を解決しますが、複雑なワークフローでは多くの場合、複数のSkillの連携が必要です。

本記事では、Skill間の依存関係の設計方法と、SKILL.mdでのマルチSkillワークフローの編成方法を紹介します。


組み合わせパターン:二つの考え方

模式描述适用场景
顺序编排Skill A の出力を Skill B の入力として使用データ処理パイプライン
并行调用複数のスキルを同時に使用し、結果を統合するマルチソースデータ集約

Claudeは単一の会話内でSkillをまたいで呼び出すことができますが、一度に「能動的に読み取る」ことができるのは1つのSkillの本文のみです。複雑なマルチSkillワークフローは、通常「オーケストレーションSkill」が全体を統括・スケジューリングします。


順次編成の例

以"上传 PDF → 提取文字 → 生成 Word 摘要报告"を例に、3つのSkillが順番に連携します。

---
name: pdf-to-word-report
description: >
  将 PDF 文档转换为 Word 格式的摘要报告,包含文字提取、
  内容分析和格式化输出三个阶段。当用户需要从 PDF 生成报告、
  提取 PDF 内容并整理为 Word 文档时触发。
---

# PDF 转 Word 摘要报告

## 工作流程

本 Skill 协调三个处理阶段,最终生成 .docx 报告。

### 阶段一:提取 PDF 文字
使用 pdf-reading Skill(位于 /mnt/skills/public/pdf-reading/)的处理逻辑:

```bash
python /mnt/skills/public/pdf-reading/scripts/extract.py \
  --input  <PDF路径> \
  --output /home/claude/extracted_text.txt
```

完成后告知用户:已提取 {N} 页内容,共 {字数} 字。

### 阶段二:生成摘要内容
对提取的文字进行内容分析,生成:
- 文档主题(1句话)
- 关键章节摘要(每章 2-3 句)
- 重要数据与结论

将摘要内容写入 /home/claude/summary.json

### 阶段三:生成 Word 报告
使用 docx Skill 的规范,调用:

```bash
python /mnt/skills/public/docx/scripts/generate.py \
  --template /mnt/skills/public/docx/assets/report_template.docx \
  --data     /home/claude/summary.json \
  --output   /mnt/user-data/outputs/report.docx
```

完成后调用 present_files 展示下载链接。

スクリプトによるSkillの組み合わせ

複数のSkillがスクリプトを共有する場合、メインスクリプトから他のSkillのスクリプトを直接呼び出して、処理パイプラインを形成できます。

实例

# 文件路径:scripts/pipeline_orchestrator.py
# 複数の Skill スクリプトの処理パイプラインをオーケストレーションする

import subprocess
import sys
import os
import json

SKILLS_BASE = "/mnt/skills/public"

def run_script(script_path: str, args: list) -> dict:
    指定されたパスのスクリプトを実行し、JSON結果を返す
    cmd = [sys.executable, script_path] + args
    result = subprocess.run(cmd, capture_output=True, text=True, timeout=120)
    if result.returncode != 0:
        return {"status": "error", "message": result.stderr}
    try:
        return json.loads(result.stdout)
    except json.JSONDecodeError:
        return {"status": "success", "raw_output": result.stdout}

def run_pipeline(pdf_path: str, output_dir: str) -> dict:
    """
完全な PDF → Word レポート生成パイプラインを実行する

阶段 1:PDF 文字提取
阶段 2:内容摘要生成(由 Claude 处理,此处跳过)
阶段 3:Word 文档生成
    """

    os.makedirs(output_dir, exist_ok=True)
    extracted_txt = os.path.join(output_dir, "extracted.txt")
    final_docx    = os.path.join(output_dir, "report.docx")

    # 阶段 1:提取 PDF 文字
    print("段階 1:PDF テキストを抽出中...")
    step1 = run_script(
        f"{SKILLS_BASE}/pdf-reading/scripts/extract.py",
        ["--input", pdf_path, "--output", extracted_txt]
    )
    if step1.get("status") == "error":
        return {"status": "error", "stage": 1, "message": step1["message"]}
    print(f" 已提取 {step1.get('pages', '?')} 页")

    # 段階 3:Word レポートを生成(要約は Claude がこのスクリプトを呼び出す前に生成して渡す)
    summary_json = os.path.join(output_dir, "summary.json")
    if not os.path.exists(summary_json):
        return {"status": "error", "stage": 3,
                "message": "缺少 summary.json,请先完成阶段 2"}

    print("段階 3:Word レポートを生成中です...")
    step3 = run_script(
        f"{SKILLS_BASE}/docx/scripts/generate.py",
        ["--data", summary_json, "--output", final_docx]
    )
    if step3.get("status") == "error":
        return {"status": "error", "stage": 3, "message": step3["message"]}

    return {"status": "success", "output": final_docx}

if __name__ == "__main__":
    pdf_path   = sys.argv[1] if len(sys.argv) > 1 else ""
    output_dir = sys.argv[2] if len(sys.argv) > 2 else "/home/claude/pipeline_output"
    result = run_pipeline(pdf_path, output_dir)
    print(json.dumps(result, ensure_ascii=False, indent=2))

循環依存の回避

Skill A が Skill B に依存し、Skill B もまた Skill A に依存する場合、循環依存が形成され、実行できなくなります。

Skillの組み合わせを設計する際は、単方向の依存関係を維持すべきです。

正确:单向依赖 正确:单向依赖 pdf-reading summarizer docx-writer 错误:循环依赖 错误:循环依赖 Skill A Skill B ← 相互依赖,无法启动

共有ツール関数

複数のSkillで必要な共通関数は、共通モジュールに抽出して、重複実装を避けることができます。

实例

# 文件路径:/home/claude/shared/file_utils.py
# 複数のスキルで共有されるファイルツール関数

import os

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

def resolve_upload(filename: str) -> str:
    """ファイル名を完全なアップロードパスに解析します"""
    if os.path.isabs(filename):
        return filename  # 既に絶対パス
    return os.path.join(UPLOAD_DIR, filename)

def resolve_output(filename: str) -> str:
    """ファイル名を完全な出力パスに解析し、ディレクトリが存在することを確認する"""
    if os.path.isabs(filename):
        path = filename
    else:
        path = os.path.join(OUTPUT_DIR, filename)
    os.makedirs(os.path.dirname(path), exist_ok=True)
    return path

# 各 Skill 脚本中使用:
# import sys; sys.path.insert(0, "/home/claude/shared")
# from file_utils import resolve_upload, resolve_output
其他扩展