Композиция и оркестрация навыков
Один навык решает одну задачу, тогда как сложные рабочие процессы часто требуют совместной работы нескольких навыков.
В этой статье рассказывается, как проектировать зависимости между навыками и как оркестрировать рабочие процессы с несколькими навыками в 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 展示下载链接。
Реализация композиции навыков через скрипты
Когда несколько навыков совместно используют скрипты, основной скрипт может напрямую вызывать скрипты других навыков, чтобы сформировать конвейер обработки.
Пример
# Организует конвейер обработки нескольких скриптов навыков
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, образуется циклическая зависимость, делающая выполнение невозможным.
При проектировании композиции навыков следует поддерживать однонаправленные зависимости.
Общие вспомогательные функции
Общие функции, необходимые нескольким навыкам, можно вынести в общий модуль, чтобы избежать дублирования реализации.
Пример
# Вспомогательные функции для работы с файлами, используемые несколькими 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