Escribir skills

Una skill es un procedimiento con nombre que el asistente puede invocar en lugar de volver a deducir los pasos cada vez. Las memorias le dicen al asistente qué es cierto. Las reglas le dicen qué no debe hacer. Las skills le dicen cómo realizar una tarea concreta, paso a paso.

Esta página explica cuándo escribir una skill, qué debe contener y cómo se almacenan y vinculan las skills.

Cuándo escribir una skill

Recurre a una skill cuando notes que el mismo patrón se repite. La señal es: "el asistente recorre una y otra vez la misma serie de pasos y a veces se salta uno".

• Procedimientos operativos. "Reenviar un webhook de Stripe en local." "Regenerar los fixtures de datos iniciales." "Ejecutar la checklist previa al lanzamiento."
• Flujos de trabajo personalizados. "Abrir un PR en borrador con las etiquetas y los revisores correctos." "Subir la versión, crear la etiqueta y hacer push."
• Guías específicas del dominio. "Crear un nuevo evento de analítica de principio a fin: columna, tipo, dashboard."

Si el patrón ocupa una o dos líneas, basta con una memoria. Recurre a una skill cuando el procedimiento tenga más de tres pasos o exija cualquier tipo de "haz esto en este orden".

Orígenes

El registro de una skill incluye un valor de origen que le indica a Pathrule dónde vive su cuerpo.

• manual. El cuerpo se escribe directamente en Pathrule y se guarda tal cual. Es la opción predeterminada. Úsala cuando quieras que el procedimiento pertenezca por completo al espacio de trabajo.
• template. Una skill inicial que proporciona Pathrule, copiada en el espacio de trabajo y editable desde ahí.
• github_ref. La skill apunta a una URL externa de GitHub. Úsala para skills publicadas por ecosistemas de skills en los que confíes.

En las skills github_ref, el espacio de trabajo guarda una instantánea del cuerpo tomada de ese origen, y la skill es de solo lectura dentro del espacio de trabajo: VS Code te indica que edites el origen.

Estructura de SKILL.md

Una skill es un pequeño archivo Markdown con frontmatter seguido del cuerpo del procedimiento.

---
name: replay-stripe-webhook
description: Replay a Stripe webhook against the local server with the right signing secret and the right idempotency key handling.
---

# Replay a Stripe webhook

Use this when a payment event from production needs to be reproduced locally.

## When to invoke

- A customer reports a missing receipt and you have the event id.
- You are debugging a webhook handler change.

## Procedure

1. Find the event in Stripe Dashboard. Copy its id.
2. Run `stripe events resend evt_xxx --webhook-endpoint we_local`.
3. Watch the local handler. It must accept and process the event without double charging.
4. If the handler returns 5xx, the customer support page is the next stop, not a retry.

## What NOT to do

- Do not replay against production webhooks.
- Do not skip the idempotency key check.

El frontmatter debe incluir name y description. Todo lo que va debajo es el cuerpo que sigue el asistente. El cuerpo puede ser tan corto o tan largo como haga falta.

Vinculación

Una skill vive en una ruta del espacio de trabajo, igual que una regla. Colócala en la ruta donde el procedimiento sea más relevante. La skill para reenviar webhooks va en services/billing/webhooks. La skill de lanzamiento va en la raíz del espacio de trabajo. Si una skill nueva tiene el mismo nombre que otra que ya existe en el espacio de trabajo, se rechaza, así que actualiza la existente en lugar de añadir una segunda copia.

El asistente descubre las skills a través del contexto que Pathrule entrega para una ruta (igual que descubre memorias y reglas), mediante pathrule_get_context, y lee una completa con pathrule_read_skill. Al sincronizar, Pathrule también escribe las skills en las carpetas de skills de los clientes que las leen, como .claude/skills para Claude Code y .agents/skills para Codex.

Invoca una skill a demanda con ::skill-name

Normalmente el asistente elige por sí solo la skill adecuada. Cuando quieras forzar una en particular, escribe :: seguido del nombre de la skill en cualquier parte de tu prompt, por ejemplo ::release-check o ::replay-stripe-webhook. Durante ese turno, el asistente trata la skill indicada como un flujo de trabajo obligatorio, sin que tengas que escribir instrucciones largas. En Claude Code y Codex, el hook del prompt detecta el marcador antes de que actúe el agente; en otros clientes, el asistente recibe la misma instrucción cuando solicita contexto a través de MCP.

Está diseñado para fallar de forma segura:

• Si el nombre coincide con más de una skill, no se invoca ninguna en lugar de intentar adivinar.
• Si el nombre no coincide con ninguna skill, se le indica al asistente que se detenga y lo resuelva contigo antes de editar nada. Puede sugerir candidatas publicadas y espera tu aprobación antes de añadir una al espacio de trabajo.
• Ignora los usos de :: propios del código, como button::before o std::vector, para no malinterpretar prompts normales.

Así, ::skill-name es una forma rápida e independiente de la ruta de traer un procedimiento conocido del equipo al turno actual.

Flujo de creación

Dos flujos llegan al mismo resultado.

• Creación manual. En VS Code, usa New Skill… en la ruta adecuada y escribe el cuerpo de SKILL.md. Desde la terminal, ejecuta pathrule skill add --path /services/billing/webhooks --name replay-stripe-webhook --description "Replay a Stripe webhook locally"; si no indicas --body, la CLI abre tu editor.
• Creación por el asistente. En Claude Code (o en cualquier cliente MCP), el usuario le pide al asistente que "convierta esto en una skill". El asistente aplica un pequeño patrón de creación de skills: captar la intención, hacerle preguntas al usuario, redactar el SKILL.md y luego llamar a pathrule_write_skill con el cuerpo completo.

En escenarios de bajo compromiso, el asistente redacta la skill en la conversación y espera tu aprobación antes de llamar a pathrule_write_skill. Por lo tanto, el registro guardado es el borrador revisado, no una escritura silenciosa en segundo plano.

Versiones y ediciones simultáneas

Las skills llevan un token de versión, igual que las memorias y las reglas. Si dos compañeros editan la misma skill, se produce un conflicto limpio en lugar de que uno sobrescriba los cambios del otro, con las mismas opciones de resolución en VS Code que para una memoria.

Antipatrones

• Skills que en realidad son memorias. Si el cuerpo dice "esto es cierto sobre cómo trabajamos", conviértelo en una memoria.
• Skills que en realidad son reglas. Si el cuerpo dice "nunca hagas X", conviértelo en una regla.
• Una sola skill que hace demasiado. Divídela en dos skills con nombre si el procedimiento tiene dos puntos de entrada distintos.
• Incorporar skills externas en las que no confías. Una skill github_ref es código que se ejecuta en las instrucciones de tu asistente. Trátala como una dependencia.

Creación en modo local y en Cloud

Los ejemplos de add en la terminal de esta página son para un espacio de trabajo de Cloud. En modo local, crea y edita entradas en Local Console, en VS Code o mediante MCP local; los comandos de conocimiento de la CLI las listan, leen y buscan.

Qué leer a continuación

• Escribir memorias para hechos y decisiones.
• Escribir reglas para restricciones.
• Referencia de herramientas MCP para las herramientas que usa el asistente para escribir skills.