CH 14 · Skill y Workflow

Word count~4,740 wordsTime~25 minPrereqCH 08, CH 13LevelReproducible

Objetivo del capítulo

Hasta ahora, cada vez que le pedías algo al Agent tenías que explicarle los requisitos con claridad. Pero algunas tareas tienen pasos fijos — como el "resumir un repo, sacar un documento" que hicimos en CH 05, o los informes semanales, organizar datos, ese tipo de tareas del día a día. Tener que repetir el proceso desde cero cada vez es demasiado desperdicio. Estas tareas merecen convertirse en "una hoja de instrucciones": decirle al Agent "cuando te encuentres este tipo de tarea, sigue este conjunto de pasos". Eso es Skill. Este capítulo aclara qué es la Skill de dsh, de dónde viene, cómo la usa el modelo, y luego instala una Skill ya hecha para usarla directamente — basta con decirle una palabra al Agent y él solito se la instala — convirtiéndola en tu "capacidad reutilizable" personal.

Un hecho clave: Skill también es un plugin

Igual que MCP y los subagentes, la Skill en dsh no es una entrada aparte; es otra combinación de plugins. Mirando el árbol de configuración, la familia de capacidades de skill se compone de cuatro piezas:

| Plugin | Qué hace | Rol | | --- | --- | | dsh-skill | Registro: fusiona los directorios de skills de varias fuentes y resuelve el "ganador" por nombre | Responsable del almacén | | dsh-skill-filesystem | Descubre skills locales desde los directorios de proyecto y usuario, monitoriza cambios de archivo | Comprador | | dsh-tool-skill | Muestra al modelo la lista de skills disponibles, provee la herramienta skill de carga | Recepción | | dsh-skill-badge | Skill insignia oficial que viene incluida, desactivada por defecto | Decoración |

Las cuatro vienen instaladas por defecto en la configuración web — así que ya puedes usarlas, sin instalar nada. Esto vuelve a ser el "todo es un plugin" de CH 08: hasta las "capacidades reutilizables" se ensamblan con plugins.

Qué es una Skill: un "cómo hacer una tarea" escrito

Las herramientas son "acciones" que el Agent puede "llamar" (leer/escribir archivos, buscar en la web); las Skills son "hojas de instrucciones" escritas para el Agent — un conjunto de instrucciones específicas para una tarea que le dicen "cuando te encuentres este tipo de tarea, sigue este conjunto de pasos".

La mayor diferencia es la reutilización: las herramientas las da el sistema, las Skills las acumulas tú. Cuando descubres un enfoque útil para una tarea, lo escribes como Skill, y a partir de ahí, cuando el Agent se encuentre el mismo tipo de tarea, no tienes que repetir los requisitos. Y las skills van según dónde estén: colocadas en el .dsh/skills del proyecto son a nivel de proyecto, solo efectivas para ese proyecto; colocadas en el directorio de usuario ~/.dsh/skills son a nivel global, disponibles en cualquier proyecto — la siguiente sección "cinco estantes" muestra la jerarquía completa.

¿Y el "Workflow"? Una Skill es el Workflow más sencillo

Una línea para recordar: una Skill es el workflow más sencillo. La esencia del workflow es "solidificar la experiencia humana en un proceso" — y una Skill es exactamente eso: entrada clara, salida clara, pasos fijos, reutilizable individualmente. Es un pequeño proceso comprimido en una sola tarea.

La diferencia está en la granularidad. Una Skill se ocupa de "cómo hacer una sola tarea" (la receta de un plato); el Workflow se ocupa de "cómo encadenar varias tareas en orden" (todo el pipeline desde comprar la verdura, lavarla hasta emplatar, gestionando también bifurcaciones, traspasos, quién va primero). En el preset Standard de dsh, "Skills" y "Workflows" son dos herramientas lado a lado — para rutinas fijas de un solo paso basta con Skill; solo para cadenas multi-paso hace falta Workflow.

Poniendo los dos lado a lado, la diferencia queda más clara:

Dimensión	Skill	Workflow
Se ocupa de	Cómo hacer una sola tarea	En qué orden encadenar varias tareas
Granularidad	Rutina fija de un paso	Pipeline multi-paso
Bifurcación y traspaso	No se encarga	Se encarga (condiciones, traspasos, orden)
Reutilización	Reutilizable individualmente	Re-orquestable según necesidad
Analogía	La receta de un plato	Todo el pipeline desde comprar la verdura hasta emplatar

Así, cuando escribes una Skill para una sola tarea fija, en realidad has construido "el workflow más sencillo".

Qué aspecto tiene una Skill

Una Skill es un archivo Markdown con frontmatter; la forma estándar es un bundle de directorio: el nombre de la carpeta es el nombre de la skill y dentro tiene que haber SKILL.md — va bien para skills que vienen con recursos acompañantes (scripts, docs de referencia, assets).

El nombre tiene que estar en kebab-case en minúsculas (^[a-z0-9]+(?:-[a-z0-9]+)*$), p. ej. code-review, weekly-report.

Un bundle de directorio estándar tiene este aspecto:

code-review/
├── SKILL.md        # Obligatorio: frontmatter + cuerpo de instrucciones
├── scripts/        # Opcional: scripts acompañantes (.py / .sh etc.)
├── references/     # Opcional: docs de referencia, plantillas de checklists
└── assets/         # Opcional: assets, archivos de muestra

SKILL.md es el único archivo obligatorio; el cuerpo puede referenciar scripts y docs de referencia del bundle mediante rutas relativas. La estructura mínima tiene este aspecto:

---
name: code-review
description: Review a piece of code against a unified checklist and output structured review comments
whenToUse: When the user asks for "code review"
---

# Code Review

Sigue este orden:

1. Lee primero el README correspondiente para entender qué problema resuelve este código;
2. Lista las exportaciones públicas y las funciones principales, anotando qué hace cada una;
3. Busca puntos de riesgo evidentes: manejo de errores, casos límite, información sensible;
4. Salida en formato tabla: Archivo / Issue / Severidad / Sugerencia.

Solo name y description son obligatorios en el frontmatter; los demás campos son opcionales:

Campo	Propósito
name	Nombre único de la Skill (kebab-case, obligatorio)
description	Descripción de una línea; el modelo la usa para juzgar "es esta tarea para mí" (obligatorio)
whenToUse	Pista extra sobre cuándo usarla (opcional)
disable-model-invocation	A true: solo el usuario puede llamarla con /name, el modelo no puede auto-cargarla (opcional)
user-invocable	A false: solo el modelo puede llamarla, el /name del usuario no funciona (opcional)

Dos interruptores: quién puede llamarla

Dos campos del frontmatter se encargan de "quién puede llamarla":

Combinación	Efecto
Ninguno	Tanto el modelo como el usuario pueden llamarla (por defecto)
disable-model-invocation: true	Solo el usuario puede llamarla vía /name; invisible en el directorio del modelo y en la herramienta skill — va bien para flujos sensibles o de alto coste para evitar que el modelo la active a la ligera
user-invocable: false	Solo el modelo puede llamarla; el /name del usuario no funciona
Ambas en off	Solo código de confianza puede llamarla; ni el modelo ni el usuario pueden tocarla

De dónde vienen las Skills: cinco "estantes"

Primero distingue dos cosas: esta sección trata de de dónde lee dsh las skills — es decir, en qué directorio local tiene que estar la skill para que sea descubierta. dsh usa el plugin dsh-skill-filesystem para escanear varios directorios raíz en un orden fijo y recoger las skills en el registro. "Instalar una skill nueva" es otra cosa: ir a un marketplace comunitario de skills (como el SkillHub de Tencent) o al Plugin Market de dsh, e instalar el SKILL.md ya hecho de otro en estos directorios estante — la sección "instalar una Skill ya hecha" de abajo hace exactamente esto.

dsh-skill-filesystem escanea varios directorios raíz en un orden fijo y recoge las skills en el registro. Cuanto más arriba, mayor prioridad — cuando aparece una skill con el mismo nombre en varios estantes, gana la que va antes:

Prioridad	Directorio	Quién lo pone ahí
1	<project-root>/.dsh/skills	Sigue al proyecto, se distribuye con el repo
2	<project-root>/.agents/skills	Compatible con la ubicación compartida de otras herramientas (p. ej. Claude Code)
3	Directorios custom desde la config customSkillDirs	Otras ubicaciones que especifiques a mano
4	<dshHome>/skills (~/.dsh/skills)	Nivel de usuario, disponible en cualquier workspace
5	<agentsHome>/skills (~/.agents/skills)	Directorio de usuario compartido con otras herramientas Agent

Cómo "ve" las Skills el modelo

Las Skills se escriben para que las vea el modelo; ¿cómo sabe cuáles existen? Este mecanismo lo provee el plugin dsh-tool-skill, instalado por defecto en la configuración web (lo puedes ver en dsh --profile web --dump-config). Funciona mediante tres mecanismos:

1. Directorio de sesión: antes de que la sesión arranque y la primera petición, el modelo recibe un mensaje persistente que lista los nombres y descripciones de una línea de todas las skills disponibles, y se le dice "antes de actuar, carga primero la skill que coincida, no te inventes a partir del resumen".
2. Herramienta skill: cuando el modelo juzga que una skill es relevante, usa skill({ name }) para cargar el cuerpo completo de instrucciones — el cuerpo vuelve como un bloque <skill_content> y se queda en el historial como resultado de herramienta. La imagen de abajo es una Trayectoria real: el modelo primero llama a la herramienta skill para cargar las instrucciones completas de aihot y luego llama a pwsh para ejecutar la verificación; las dos llamadas de herramienta se ven clarísimas en la Trayectoria.

3. Gesto de usuario /name: escribes /code-review directamente en el cuadro de entrada y las instrucciones de la skill se inyectan en la ronda como un mensaje de usuario, el modelo simplemente las sigue. Atención: ese nombre tiene que existir realmente en los estantes del workspace y permitir invocación del usuario — escribir un nombre de skill que no existe se trata como texto plano y no hace nada.

Un detalle: tras la inyección /name del usuario, el modelo no vuelve a usar la herramienta skill para cargarla — así se evita meter dos veces las mismas instrucciones y quemar tokens.

Si le pides al modelo "qué skills tienes ahora" y no te las sabe decir, primero confirma que la configuración web tenga el plugin @deepseek-ai/dsh-tool-skill (un vistazo con dsh --profile web --dump-config).

Manos a la obra: instala una Skill ya hecha (úsala tal cual)

La esencia de instalar una skill ya hecha es meter el SKILL.md ya hecho de otro en un directorio "estante" de dsh (normalmente el .dsh/skills a nivel de proyecto) — la comunidad ya tiene un buen lote de skills hechas para tomar.

Aquí usamos aihot como ejemplo: es una skill de tipo búsqueda del conocido blogger tech de IA "Digital Life Kazike", especializado en capturar noticias de IA del día a día y movimientos del sector.

Paso 1: dile una palabra al Agent, deja que él solito la instale

No hace falta que busques archivos y crees directorios tú. Vuelve a la conversación y di:

Please install the AIHOT Skill: https://aihot.virxact.com/aihot-skill/README.md Tell me if I need to start a new session after installation. If the installer supports it, please append: --actor your-Actor-ID

El ID detrás de --actor te lo asignan al registrarte en la plataforma AIHOT y se escribe en el local .aihot-actor-id tras la instalación; el Agent lo llevará para identificarse al pedir.

El Agent lo hará él solito: irá al sitio oficial, descargará el SKILL.md de AIHOT y los archivos acompañantes, los colocará en la ubicación estándar de descubrimiento de DSH (~/.agents/skills/aihot/), hará verificación de integridad SHA-256 uno a uno, escribirá la config de actor, generará .gitignore y te reportará el resultado. Tras la instalación, no hace falta abrir una sesión nueva — ya está en el <available_skills> de la sesión actual, lista para usar.

Paso 2: haz que el modelo reporte la nueva Skill

Vuelve a la conversación y pregunta:

What skills do you have now? What does the aihot skill do?

El modelo te lo reportará — no has escrito ni una línea de código y ya tienes una capacidad reutilizable. También te dirá qué hace concretamente esta skill (aihot consulta las noticias de IA actuales en chino en tiempo real a través de la API anónima de solo lectura de AIHOT, no se "inventa" noticias a partir de la memoria de entrenamiento).

Paso 3 (opcional): haz que el modelo la use

Solo di "use aihot to scrape today's AI news" y el modelo cargará esta skill para scrapear. El flujo de búsqueda refinado de otro ya se ha convertido en tu capacidad — eso es "úsala tal cual".

Errores comunes

Trampa	Cómo evitarla
Olvidaste description	Falta el campo obligatorio, la skill entera se descarta tras un aviso
Nivel de directorio mal puesto	Solo se reconoce <root>/<name>/SKILL.md o <root>/<name>.md, un nivel, no anides más adentro
El modelo no la usa proactivamente	Escribe en description claramente "cuándo usarla" (whenToUse también ayuda); si de verdad te preocupa, usa /name para inyectarla directamente
Editaste el cuerpo pero el modelo no reacciona	Las ediciones del cuerpo no afectan al resumen del directorio; el modelo tiene que "recargar" una vez; solo editando campos de resumen como description se refleja ya en el directorio

Qué aprendiste en este capítulo

Apruebas si puedes completar los siguientes puntos:

• [ ] Enunciar que una Skill es "instrucciones reutilizables escritas para el Agent" y que la diferencia con una herramienta es la reutilización
• [ ] Saber que la Skill en dsh también es un plugin (registro de skills + descubrimiento por filesystem + consumidor de herramienta)
• [ ] Poder enunciar la estructura de una Skill (frontmatter con name / description obligatorios, whenToUse opcional)
• [ ] Conocer la prioridad de los cinco estantes (proyecto .dsh/skills la más alta, directorio de usuario después, usable entre proyectos)
• [ ] Haber ejecutado "dile al Agent una frase → se instala la skill → el modelo la reporta → el modelo la carga y la usa"
• [ ] Distinguir los dos interruptores disable-model-invocation y user-invocable