Crear skills de Rakenne con el Skill Workshop

Las skills de Rakenne son flujos de elaboración de documentos que el agente puede ejecutar cuando los usuarios describen una tarea. El Skill Workshop es un tipo de proyecto dedicado que te permite crear y publicar tus propias skills conversando con el agente — sin código. Este tutorial recorre el flujo completo: desde crear un proyecto workshop hasta publicar una skill en la biblioteca de tu organización.

Qué necesitas

• Acceso a una instancia de Rakenne donde puedas crear proyectos.
• Una idea clara de un flujo de dominio que quieras convertir en skill (p. ej. “redactar actas a partir de transcripciones”, “revisar contratos con nuestro playbook”, “crear checklist de cumplimiento a partir del reglamento X”).

Paso 1: Crear un proyecto Skill Workshop

1. En Rakenne inicia Crear proyecto (o equivalente en tu interfaz).
2. Al elegir tipo de proyecto selecciona Skill Workshop.
3. Pon un nombre al proyecto (p. ej. “Mis skills”) y créalo.

El espacio de trabajo se aprovisiona con:

• Skill skill-creator — Una skill integrada en .pi/skills/skill-creator/ que guía el flujo de creación.
• AGENTS.md — Instrucciones que indican al agente que es un workspace de creación de skills y que las skills van en output/.
• output/ — Un directorio vacío donde vivirá cada skill que crees (un subdirectorio por skill).

Usas el mismo espacio de trabajo que ya conoces: chat con el agente, árbol de archivos, vista previa de documentos. La única diferencia es la plantilla y el objetivo: producir skills en lugar de un solo documento.

Paso 2: Iniciar la conversación de creación

Abre el proyecto y, en el chat, di qué quieres construir. Por ejemplo:

• “Quiero crear una skill que convierta transcripciones de reuniones en notas estructuradas con decisiones y acciones.”
• “Necesitamos una skill que ayude a redactar evaluaciones de impacto en la privacidad usando nuestra plantilla interna y PIPEDA.”

El agente usará la skill skill-creator y no creará archivos hasta haber entendido tu flujo. Te hará preguntas de forma estructurada (fase Elicit).

Paso 3: Responder a las preguntas de elicitación

El agente preguntará sobre:

1. Para qué sirve el flujo — Dominio y tarea (p. ej. actas, revisión de contratos, cumplimiento).
2. Qué lo dispara — Cuándo usaría alguien esta skill (p. ej. “cuando el usuario tiene una transcripción y quiere notas estructuradas”).
3. Qué pasos implica — La secuencia (p. ej. recibir entrada → extraer decisiones y acciones → confirmar ambigüedades → producir documento).
4. Cómo es la salida — Tipo de documento, secciones, formato (p. ej. resumen ejecutivo, registro de decisiones, acciones).
5. Conocimiento de dominio — Reglamentos, estándares, plantillas o material de referencia que el agente debe usar.

Responde en lenguaje natural. El agente convertirá tus respuestas en una skill estructurada; no necesitas conocer markdown ni YAML. Si tienes plantillas o documentos de referencia puedes añadirlos después o describirlos para que el agente pueda referenciar placeholders.

Paso 4: Dejar que el agente haga scaffold y escriba la skill

Cuando el agente tenga suficiente información, hará:

1. Elegir un slug — Un identificador en kebab-case (p. ej. meeting-notes, contract-review-playbook).
2. Llamar a scaffold_skill — Crea output/{slug}/ con una plantilla SKILL.md y opcionalmente los directorios references/ y assets/.
3. Editar SKILL.md — Rellena los pasos del flujo, enlaces a archivos de referencia y lenguaje de disparo en la descripción.
4. Añadir archivos reference y asset — El conocimiento de dominio va en references/; plantillas o ejemplos de salida en assets/.

Todo ocurre en el chat; puedes seguir el árbol de archivos y abrir archivos para revisar. Las skills se escriben solo bajo output/.

Paso 5: Validar y refinar

Antes de dar la skill por lista, el agente ejecutará validate_skill. Comprueba:

• SKILL.md existe y tiene frontmatter YAML válido (name, description).
• Calidad de la descripción — La descripción incluye lenguaje de disparo (p. ej. “Use when…”, “Use for…”).
• Longitud del body — Body de SKILL.md por debajo de 500 líneas (contenido largo debe ir en references/).
• Integridad de referencias — Los enlaces en SKILL.md apuntan a archivos existentes; sin enlaces rotos.
• metadata.json — Presente y válido (o aviso si falta; lo añadirás en el siguiente paso).

Si algo falla, el agente sugerirá correcciones (p. ej. añadir lenguaje de disparo, corregir una ruta, mover contenido a un archivo de referencia). Puedes refinar en el chat y revalidar hasta que pasen todas las comprobaciones.

Paso 6: Preparar metadatos para la biblioteca

Cuando estés satisfecho con el contenido de la skill, el agente preparará para publicar:

1. Ejecutar preview_metadata — Muestra cómo aparecerá la skill en la biblioteca. Si no existe metadata.json, se genera un borrador a partir del frontmatter de SKILL.md.
2. Editar metadata.json — Juntos configurarás title (nombre legible para la biblioteca), description (resumen corto), tags (sustantivos comunes en inglés orientados al dominio, p. ej. “Productivity”, “Meetings”, “Legal”, “Compliance”) y examples (dos o tres prompts de ejemplo).
3. Validar de nuevo — Un último validate_skill asegura que metadatos y estructura estén completos.

Después, el agente te dirá que la skill está lista para publicar.

Paso 7: Publicar en tu biblioteca

1. En la barra del proyecto haz clic en Publish Skill.
2. Un diálogo lista las skills en tu directorio output/ (cada carpeta que contiene un SKILL.md). Selecciona la skill a publicar.
3. Confirma. El frontend llama a la API de publicación; la skill se copia a la biblioteca de skills de tu organización y se registra en el catálogo.
4. Verás un mensaje de éxito (p. ej. “Skill publicada en la biblioteca”). La skill queda disponible al instalar skills en cualquier proyecto de tu tenant. Volver a publicar el mismo slug actualiza la skill existente.

Anatomía de una skill Rakenne

Una skill mínima en output/{slug}/ se compone de:

• SKILL.md — Obligatorio. Frontmatter YAML con name (slug) y description (incluyendo lenguaje de disparo). Body: pasos del flujo, reglas y enlaces a referencias.
• metadata.json — Obligatorio para publicar. title, description, tags (array), examples (array de prompts de ejemplo). Lo usa la UI de la biblioteca.
• references/ — Opcional. Archivos Markdown (u otros) con conocimiento de dominio; enlazados desde SKILL.md para que el agente pueda leerlos durante el flujo.
• assets/ — Opcional. Plantillas o recursos estáticos que el agente usa al producir la salida (p. ej. meeting_notes_template.md).

El flujo skill-creator mantiene SKILL.md conciso y mueve el contenido detallado a references/ para que el agente tenga un flujo claro y escaneable más contexto rico cuando haga falta.

Consejos

• Un flujo por skill — Si tienes varios flujos distintos, crea una skill por flujo; puedes crear varias skills en el mismo proyecto workshop (cada una en su output/{slug}/).
• El lenguaje de disparo importa — El agente usa la description de la skill para decidir cuándo activarla. Frases como “Use when the user wants to…”, “Use for drafting…” o “Use to generate…” ayudan a emparejar la intención.
• Itera en el workshop — Puedes reabrir el proyecto cuando quieras, editar archivos o chatear con el agente para cambiar la skill, revalidar y Publish Skill de nuevo para actualizar la copia en la biblioteca.
• Sin extension.ts para skills de dominio — El Skill Workshop es para skills basadas en markdown (SKILL.md + references + assets). Las extensiones TypeScript quedan fuera del flujo guiado; el skill-creator no crea ni edita extension.ts.

Próximos pasos

• Usa Session Management and Context Hygiene para que cada tarea de creación quede en una sesión focalizada.
• Lee Rakenne 0.2.0 — Skill Workshop y más para el conjunto completo de funciones y mejoras de la biblioteca.
• Después de publicar, instala tu skill en un proyecto de elaboración de documentos y ejecuta algunos prompts de ejemplo para confirmar el comportamiento esperado.