Композиция и оркестрация навыков

Один навык решает одну задачу, тогда как сложные рабочие процессы часто требуют совместной работы нескольких навыков.

В этой статье рассказывается, как проектировать зависимости между навыками и как оркестрировать рабочие процессы с несколькими навыками в SKILL.md.


Паттерны композиции: два подхода

ПаттернОписаниеПрименимый сценарий
Последовательная оркестрацияВыход навыка A используется как вход навыка BКонвейер обработки данных
Параллельный вызовИспользовать несколько навыков одновременно и объединять результатыАгрегация данных из нескольких источников

Claude может выполнять вызовы между навыками в одном диалоге, но может «активно читать» тело только одного навыка за раз. Сложные рабочие процессы с несколькими навыками обычно координируются «навыком оркестрации».


Пример последовательной оркестрации

На примере«Загрузка PDF → Извлечение текста → Создание сводного отчёта Word»рассмотрим: три навыка взаимодействуют последовательно.

---
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 展示下载链接。

Реализация композиции навыков через скрипты

Когда несколько навыков совместно используют скрипты, основной скрипт может напрямую вызывать скрипты других навыков, чтобы сформировать конвейер обработки.

Пример

# Путь к файлу: scripts/pipeline_orchestrator.py
# Организует конвейер обработки нескольких скриптов навыков

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))

Избегание циклических зависимостей

Когда навык A зависит от навыка B, а навык B зависит от навыка A, образуется циклическая зависимость, делающая выполнение невозможным.

При проектировании композиции навыков следует поддерживать однонаправленные зависимости.

Correct: One-way dependency Correct: One-way dependency pdf-reading summarizer docx-writer Incorrect: Circular dependency Incorrect: Circular dependency Skill A Skill B ← Mutually dependent, cannot start

Общие вспомогательные функции

Общие функции, необходимые нескольким навыкам, можно вынести в общий модуль, чтобы избежать дублирования реализации.

Пример

# Путь к файлу: /home/claude/shared/file_utils.py
# Вспомогательные функции для работы с файлами, используемые несколькими Skills

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
Другие расширения