Skills composición y orquestación

Un solo Skill resuelve un problema único, pero los flujos de trabajo complejos suelen requerir que varios Skills cooperen entre sí.

Este artículo explica cómo diseñar las dependencias entre Skills y cómo orquestar flujos de trabajo con múltiples Skills en SKILL.md.


Patrones de composición: dos enfoques

PatrónDescripciónEscenario de aplicación
Orquestación secuencialLa salida del Skill A se usa como entrada del Skill BPipeline de procesamiento de datos
Llamada paralelaUsar varios Skills al mismo tiempo y combinar los resultados.Agregación de datos de múltiples fuentes

Claude puede realizar llamadas entre Skills en una sola conversación, pero solo puede "leer activamente" el contenido de un Skill a la vez. Un flujo de trabajo complejo con múltiples Skills suele ser coordinado por un "Skill orquestador".


Ejemplo de orquestación secuencial

conSubir PDF → Extraer texto → Generar informe de resumen en WordComo ejemplo, tres Skills colaboran en secuencia.

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

Combinar Skills mediante scripts

Cuando varios Skills comparten scripts, el script principal puede invocar directamente los scripts de otros Skills para formar un pipeline de procesamiento.

Ejemplo

# Ruta de archivo: scripts/pipeline_orchestrator.py
# Orquesta el pipeline de procesamiento de los scripts de varios Skills

import subprocess
import sys
import os
import json

SKILLS_BASE = "/mnt/skills/public"

def run_script(script_path: str, args: list) -> dict:
    """Ejecuta el script en la ruta especificada y devuelve el resultado 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:
    """
Ejecuta el pipeline completo de generación de informe PDF → Word

Fase 1: Extracción de texto del PDF
Fase 2: Generación del resumen de contenido (procesada por Claude, se omite aquí)
Fase 3: Generación del documento de 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")

    # Fase 1: Extraer texto del PDF
    print("Fase 1: Extrayendo texto del 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" Se extrajeron {step1.get('pages', '?')} páginas")

    # Fase 3: Generar informe de Word (el resumen lo genera Claude y se pasa antes de llamar a este script)
    summary_json = os.path.join(output_dir, "summary.json")
    if not os.path.exists(summary_json):
        return {"status": "error", "stage": 3,
                "message": "Falta summary.json; complete primero la fase 2"}

    print("Fase 3: Generando informe de 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))

Evitar dependencias circulares

Cuando el Skill A depende del Skill B y el Skill B depende del Skill A, se forma una dependencia circular que impide la ejecución.

Al diseñar la composición de Skills, se deben mantener dependencias unidireccionales.

Correcto: dependencia unidireccional Correcto: dependencia unidireccional pdf-reading summarizer docx-writer Error: dependencia circular Error: dependencia circular Skill A Skill B ← Dependen mutuamente, no se puede iniciar

Compartir funciones de utilidad

Las funciones comunes que necesitan varios Skills pueden extraerse en un módulo público para evitar implementaciones duplicadas.

Ejemplo

# Ruta de archivo: /home/claude/shared/file_utils.py
# Funciones de utilidad de archivos compartidas por varios Skills

import os

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

def resolve_upload(filename: str) -> str:
    """Convierte un nombre de archivo en la ruta de subida completa"""
    if os.path.isabs(filename):
        return filename  # Ya es una ruta absoluta
    return os.path.join(UPLOAD_DIR, filename)

def resolve_output(filename: str) -> str:
    """Convierte un nombre de archivo en la ruta de salida completa y asegura que el directorio exista"""
    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

# Uso en los scripts de cada Skill:
# import sys; sys.path.insert(0, "/home/claude/shared")
# from file_utils import resolve_upload, resolve_output
Otras extensiones