@dforce2055/dai 0.6.0 → 0.8.0

package/docs/adr/0015-jira-corporativo.md

@@ -0,0 +1,104 @@
+# ADR-0015 — `dai publish` en un Jira corporativo (campos propios, épicas, TLS)
+
+- **Estado:** aceptado
+- **Fecha:** 2026-07-15
+- **Decide:** lead / arquitecto de la metodología
+
+## Contexto
+
+`dai publish` funcionaba contra un Jira limpio y fallaba contra uno real. Lo vimos en
+vivo: un analista funcional intentó publicar su primera US en el Jira de su empresa y
+`createUS` mandaba solo `project`, `issuetype`, `summary` y `description`. El proyecto
+exigía un campo propio (`Tipo de trabajo`, `customfield_10042`) → **400 en todos
+los intentos**. Además el proxy corporativo intercepta TLS con su propia CA, y Node no
+usa el trust store del sistema → `fetch` reventaba antes de llegar.
+
+**Lo que pasó después es el verdadero motivo de esta ADR.** El asistente, bloqueado por
+el CLI, improvisó: leyó el schema del campo por su cuenta, armó la llamada a la API de
+Jira con `node -e`, y para pasar el proxy corrió `NODE_TLS_REJECT_UNAUTHORIZED=0` —
+apagando la verificación de certificado **mientras mandaba el token de Jira**. Lo
+reportó como *"nota técnica resuelta en el camino"*. Su propio razonamiento fue:
+*"bypassing dai's limitation entirely"*.
+
+Publicó bien, de casualidad. Pero eso es exactamente lo que la capa 2 de la
+[ADR-0002](0002-agnostico-del-asistente.md) existe para evitar: *"el output es idéntico
+con Claude, con Copilot, o sin ningún asistente"*. **Cuando el CLI no llega, el agente
+inventa** — y el improviso siguiente puede no respetar el contrato del `ac_hash`, y ahí
+la trazabilidad se rompe en silencio.
+
+La lección: **un CLI que no cubre el caso real no es neutral, es una invitación a
+puentearlo.** Cada hueco de la capa 2 se llena con inteligencia no determinista.
+
+## Decisión
+
+**1. Los campos propios se declaran, con nombre humano y opciones válidas.**
+`.dai/jira-fields.json` (o `DAI_JIRA_FIELDS_FILE`), por issuetype:
+
+```json
+{
+  "Story": {
+    "clasificacion": {
+      "field": "customfield_10042",
+      "shape": "select",
+      "default": "Mejora",
+      "options": ["Mejora", "Corrección"]
+    }
+  }
+}
+```
+
+- **Por issuetype**, porque en Jira corporativo los campos obligatorios de una Epic y de
+  una Story casi nunca son los mismos.
+- **`default` + `--field alias=valor`**, porque el valor **no es config fija**: la
+  clasificación es Mejora o Corrección *según la US*. Un default fijo publicaría todas
+  iguales — un dato incorrecto en Jira, en silencio, que es peor que fallar.
+- **`options` valida ANTES de la red.** Un typo da `'Mejraa' no es opción de
+  'clasificacion' — válidas: Mejora | Corrección`, no un 400 críptico.
+- **Un campo declarado tiene que resolver** (default u override): se declara porque Jira
+  lo exige. Si es opcional, no se declara.
+- **`shape`** cubre las formas de Jira (`select` `{value:X}` · `text` X · `multi`
+  `[{value:X}]`), con **`raw`** como escape hatch para cualquier cosa rara: dai no
+  necesita entender todo Jira para no estorbar.
+- **Sin archivo → `{}`.** Un Jira sin campos obligatorios publica igual que siempre.
+
+**2. `--parent` y `--issuetype`.** `--parent` cuelga la US de su épica (`createUS` nunca
+mandaba `parent`); `--issuetype Epic` permite que **`grill-epic` publique épicas por
+CLI**, que hasta hoy no tenían fallback y quedaban como un `.md` para pegar a mano.
+
+**3. Un fallo de TLS enseña el camino correcto, y desaconseja el peligroso.** `daiFetch`
+traduce los códigos de certificado a un error que manda a **`NODE_EXTRA_CA_CERTS`** y
+dice explícitamente por qué `NODE_TLS_REJECT_UNAUTHORIZED=0` no es una alternativa. dai
+**nunca** baja la verificación por su cuenta.
+
+**4. `DAI_JIRA_PROJECT` se valida.** `PROJ-42` es un ticket, no un proyecto — el
+error de config más común. El mensaje da los dos caminos: `DAI_JIRA_PROJECT=PROJ`, o
+`--parent PROJ-42` si lo que querías era colgarla de esa épica.
+
+**5. La constitución prohíbe las dos maniobras**, para todos los asistentes:
+
+> - **No bajes la seguridad para avanzar:** si una llamada falla por el certificado,
+>   declara la CA. Nunca `NODE_TLS_REJECT_UNAUTHORIZED=0`, `verify=False`, `-k`.
+> - **Si el CLI no llega, para y dilo:** no improvises una llamada a la API por fuera.
+
+## Consecuencias
+
+- **`dai publish` sirve en un Jira corporativo**, que es donde vive el usuario real.
+- **`grill-epic` gana un fallback CLI**: MCP → `dai publish --issuetype Epic` → `.md`.
+- **El caso que motivó el bypass ahora está cubierto**, que es la única forma honesta de
+  pedirle a un agente que no improvise: no dejarle el hueco.
+- **`dai doctor`** valida la clave de proyecto y que el archivo de campos parsee. Sigue
+  **sin** verificar que el token sirva — eso es red, y lo dice `dai publish`. El chequeo
+  ahora lo admite en voz alta en vez de dar un ✓ engañoso.
+- **ClickUp queda con el mismo hueco de TLS.** `daiFetch` está listo para adoptarse allá
+  con un import; no lo hicimos ahora por alcance.
+
+## Alternativas descartadas
+
+- **Una sola variable `DAI_JIRA_FIELDS={"customfield_10042":{"value":"Mejora"}}`.**
+  Una línea ilegible, sin distinguir Story de Epic, sin validación, y con el valor fijo
+  — el problema original.
+- **Resolver los nombres de campo contra `createmeta` de Jira.** Menos config, pero pide
+  red para armar el payload, y falla distinto según permisos. Un archivo explícito se lee
+  y se versiona.
+- **Que dai reintente sin verificar TLS si el certificado falla.** Es exactamente lo que
+  hizo el agente. Automatizarlo sería institucionalizar el bug.

package/docs/adr/README.md

@@ -17,6 +17,10 @@ decisión cambia, se escribe un ADR nuevo que supersede al viejo. Molde en
 | [0009](0009-adaptador-cursor.md) | Adaptador nativo para Cursor (skills + rules) con `dai init`/`install`/`doctor` | propuesto |
 | [0010](0010-versionado-y-upgrade.md) | Versionado y upgrade: compatibilidad por semver, `doctor` version-drift, `dai sync` aditivo | propuesto |
 | [0011](0011-archive-gate-de-aprobacion.md) | `archive` es un gate de aprobación: `dai archive` (comando) lo corre el aprobador; `check`/`ls` saltean `archive/` | aceptado |
+| [0012](0012-upgrade-self-update-del-cli.md) | `dai upgrade`: self-update del CLI + `dai sync` del scaffold | aceptado |
+| [0013](0013-skills-externas-install-from.md) | `dai skills install --from`: skills externas por-stack, sin registro ni gatekeeping | aceptado |
+| [0014](0014-copilot-agent-skills.md) | Copilot lee `SKILL.md` nativo (Agent Skills): se elimina el adaptador `.prompt.md` — modifica la 0002 | aceptado |
+| [0015](0015-jira-corporativo.md) | `dai publish` en Jira corporativo: campos propios declarados, `--parent`/`--issuetype`, TLS con CA (nunca apagar la verificación) | aceptado |
 
 > Estas son las decisiones que cierran las "Decisiones abiertas" de
 > [`METODOLOGIA.md §7`](../METODOLOGIA.md) y las enmiendas al

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dforce2055/dai",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Metodología de desarrollo asistido por IA — CLI de acciones deterministas (trazabilidad QUÉ↔CÓMO).",
   "repository": { "type": "git", "url": "git+https://github.com/dforce2055/dai.git" },
   "homepage": "https://dforce2055.github.io/dai/",

package/skills/dai-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dai-review
-description: Revisa una Pull/Merge Request de un repo remoto (GitHub o GitLab) de forma consciente de la metodología dai, y deja un comentario estándar en español con errores y mejoras. Corre `dai check` (¿la US está atrasada?), valida el Definition of Done, hace el review de código (correctitud + calidad), compone el comentario estándar y lo postea — vía el MCP del forge si está disponible, o vía `dai forge comment` (token) si no. Invocar como /dai-review <URL-de-la-PR o número>. Usar en el paso 6 de SCRUM-CON-IA (code review), antes de que un partner humano firme.
+description: "Revisa una Pull/Merge Request de un repo remoto (GitHub o GitLab) de forma consciente de la metodología dai, y deja un comentario estándar en español con errores y mejoras. Corre `dai check` (¿la US está atrasada?), valida el Definition of Done, hace el review de código (correctitud + calidad), compone el comentario estándar y lo postea — vía el MCP del forge si está disponible, o vía `dai forge comment` (token) si no. Invocar como /dai-review <URL-de-la-PR o número>. Usar en el paso 6 de SCRUM-CON-IA (code review), antes de que un partner humano firme."
 ---
 
 # dai-review — review de PR consciente de la metodología

package/skills/doc-to-backlog/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: doc-to-backlog
-description: Toma un documento de análisis (PDF, Word, o un archivo en Drive/SharePoint/ClickUp vía MCP) y produce un BACKLOG CANDIDATO — un mapa de épicas y User Stories propuestas — para que el funcional lo priorice y lo valide. NO emite US ni épicas finales: extrae candidatos marcados "sin validar" y hace handoff de cada sobreviviente a grill-epic / grill-user-story (modo refinar). Es la puerta de entrada del caso "llegué con un documento y quiero sacar el backlog". Invocar como /doc-to-backlog con el path o el link del documento. Usar antes de grill-epic / grill-user-story cuando el input es un doc grande.
+description: "Toma un documento de análisis (PDF, Word, o un archivo en Drive/SharePoint/ClickUp vía MCP) y produce un BACKLOG CANDIDATO — un mapa de épicas y User Stories propuestas — para que el funcional lo priorice y lo valide. NO emite US ni épicas finales: extrae candidatos marcados \"sin validar\" y hace handoff de cada sobreviviente a grill-epic / grill-user-story (modo refinar). Es la puerta de entrada del caso \"llegué con un documento y quiero sacar el backlog\". Invocar como /doc-to-backlog con el path o el link del documento. Usar antes de grill-epic / grill-user-story cuando el input es un doc grande."
 ---
 
 # doc-to-backlog

package/skills/grill-epic/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: grill-epic
-description: Interroga a un PO o analista funcional para producir una ÉPICA bien formada — un bloque grande de valor de negocio que se parte en varias User Stories — siguiendo el template del método. O toma una US que resultó demasiado grande y la promueve a épica. Se queda a nivel funcional/alcance: define el objetivo de negocio y la partición en US, NUNCA criterios de aceptación (esos viven en cada US) ni diseño técnico. Al terminar, publica la épica en Jira/ClickUp (o deja un .md) y hace handoff de cada US hija a grill-user-story. Invocar como /grill-epic, opcionalmente con un título, un ID/URL del tracker, o una US grande a promover. Usar cuando algo es demasiado grande para una sola US.
+description: "Interroga a un PO o analista funcional para producir una ÉPICA bien formada — un bloque grande de valor de negocio que se parte en varias User Stories — siguiendo el template del método. O toma una US que resultó demasiado grande y la promueve a épica. Se queda a nivel funcional/alcance: define el objetivo de negocio y la partición en US, NUNCA criterios de aceptación (esos viven en cada US) ni diseño técnico. Al terminar, publica la épica en Jira/ClickUp (o deja un .md) y hace handoff de cada US hija a grill-user-story. Invocar como /grill-epic, opcionalmente con un título, un ID/URL del tracker, o una US grande a promover. Usar cuando algo es demasiado grande para una sola US."
 ---
 
 # grill-epic
@@ -60,10 +60,18 @@ la forma. Nunca reescribas el formato inline.
 1. **Armar la épica** con el formato de `templates/epica.md`: metadata (`ID`, autor,
    estado, US que la componen) + objetivo + alcance (in/out) + lista de US + métricas +
    dependencias.
-2. **Publicar en el tracker** (según `DAI_PM` del `.env`: `jira` → MCP de Atlassian ·
-   `clickup` → MCP de ClickUp · `md`/sin token → `.md` para pegar a mano). **No asumas
-   el tracker: lee `DAI_PM` primero.** Crear el ticket de épica; las US hijas se crean
-   como tickets vinculados (o quedan listadas para crearse).
+2. **Publicar en el tracker.** **No asumas el tracker: lee `DAI_PM` del `.env` primero.**
+   Tres caminos, mismo contenido:
+   - **Con MCP** (`jira` → MCP de Atlassian · `clickup` → MCP de ClickUp): crea el ticket
+     de épica; las US hijas se crean como tickets vinculados (o quedan listadas).
+   - **Sin MCP, con token** (`DAI_PM=jira` + token en `.env`): escribe la épica como `.md`
+     y publícala con **`dai publish <epica.md> --issuetype Epic`**. Devuelve el key. Si el
+     proyecto exige campos propios, van con `--field alias=valor` (los declarados en
+     `.dai/jira-fields.json`; `dai doctor` te los lista). Después, cada US hija se cuelga
+     con `dai publish <us.md> --parent <KEY-de-la-épica>`.
+   - **Sin token** (o `DAI_PM=md`): deja el `.md` para pegar a mano, y avisa el motivo.
+   - Si `dai` falla, **para y reporta el error tal cual**. No improvises una llamada a la
+     API del tracker por fuera: publicaría igual pero rompería el link en silencio.
 3. **Handoff.** Ofrecer pasar **cada US hija** por `/grill-user-story` para convertirla
    de "título en la lista" a US testeable con criterios. Ese es el paso que las hace
    linkeables (`dai link-us`).

package/skills/grill-intent/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: grill-intent
-description: Gate 0 of the SDD workflow — challenge the *problem* behind a clean user story before any spec is generated. Interrogates whether this is the right problem, for the right user, within constraints, and whether the story's implied solution is a premature jump. Produces intent.md and a verdict that can be "go to spec", "reframe", or "don't build". In the spirit of grill-me, specialized for problem-challenge. Invoke as /grill-intent on a user story (the output of grill-user-story). Use after grill-user-story and before openspec propose.
+description: "Gate 0 of the SDD workflow — challenge the *problem* behind a clean user story before any spec is generated. Interrogates whether this is the right problem, for the right user, within constraints, and whether the story's implied solution is a premature jump. Produces intent.md and a verdict that can be \"go to spec\", \"reframe\", or \"don't build\". In the spirit of grill-me, specialized for problem-challenge. Invoke as /grill-intent on a user story (the output of grill-user-story). Use after grill-user-story and before openspec propose."
 ---
 
 # grill-intent — Gate 0, challenge the problem

package/skills/grill-user-story/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: grill-user-story
-description: Interroga a un PO o analista funcional para producir una User Story funcional y testeable siguiendo el formato del modelo de trazabilidad — o pule una US vaga existente. Se queda a nivel funcional/usuario y se niega a derivar en diseño técnico o a emitir una US con criterios no testeables. Al terminar, PUBLICA la US en el tracker configurado del repo (Jira o ClickUp, según DAI_PM del .env) usando su MCP; si no hay MCP/token, deja un .md con el mismo formato para copiar y pegar. Invocar como /grill-user-story, opcionalmente con un título, un ID/URL del tracker, y/o una US rústica existente. Usar antes de opsx:propose, o cuando alguien dice "necesito una US", "convierte esto en una US como corresponde", o "esta historia está muy vaga".
+description: "Interroga a un PO o analista funcional para producir una User Story funcional y testeable siguiendo el formato del modelo de trazabilidad — o pule una US vaga existente. Se queda a nivel funcional/usuario y se niega a derivar en diseño técnico o a emitir una US con criterios no testeables. Al terminar, PUBLICA la US en el tracker configurado del repo (Jira o ClickUp, según DAI_PM del .env) usando su MCP; si no hay MCP/token, deja un .md con el mismo formato para copiar y pegar. Invocar como /grill-user-story, opcionalmente con un título, un ID/URL del tracker, y/o una US rústica existente. Usar antes de opsx:propose, o cuando alguien dice \"necesito una US\", \"convierte esto en una US como corresponde\", o \"esta historia está muy vaga\"."
 ---
 
 # grill-user-story
@@ -65,11 +65,24 @@ La US se produce UNA vez con el formato de `../../templates/formato-us.md`. Lo q
    - Si NO hay MCP del tracker conectado (pero sí `DAI_PM=jira|clickup` + token en `.env`):
      escribe la US como `.md` (formato `formato-us.md`) y publícala con el comando:
      **`dai publish <ruta-del-md>`** → crea el issue/tarea vía REST y devuelve el key.
-     (Jira necesita además `DAI_JIRA_PROJECT` en el `.env`.)
+     (Jira necesita además `DAI_JIRA_PROJECT` en el `.env` — la clave del **proyecto**,
+     `PROJ`, no la de un ticket.)
+   - **Si la US pertenece a una épica:** `dai publish <us.md> --parent <KEY-de-la-épica>`.
+   - **Si el proyecto exige campos propios** (típico en Jira corporativo): van con
+     `--field alias=valor`, repetible. Los alias son los de `.dai/jira-fields.json`, y
+     `dai doctor` te dice cuáles hay. Si el valor cambia según la US (p. ej. una
+     clasificación Mejora/Corrección), **pregúntaselo a la persona** durante el
+     interrogatorio — no lo elijas tú, es una decisión de negocio.
+     Ej.: `dai publish us.md --parent PROJ-42 --field clasificacion=Corrección`
    - Si tampoco hay token (o `DAI_PM=md`): deja solo el `.md` para que la persona lo
      pegue a mano en el tracker. Avisa el motivo.
    - El contenido es **idéntico** en los tres caminos (MCP / `dai publish` / manual).
-4. **Estado.** Dejar la US en `pulida`. Ofrecer que el dev siga con `dai link-us <ID>` → `opsx:propose` (lado técnico).
+4. **Si `dai publish` falla, para y reporta el error tal cual.** No improvises una llamada
+   a la API del tracker por fuera, ni bajes la verificación TLS para pasar un proxy: el
+   atajo publica igual, pero el `## Criterios de aceptación` puede quedar mal formado y
+   **el link QUÉ↔CÓMO se rompe en silencio**. Si el error nombra un campo obligatorio que
+   falta, decláralo en `.dai/jira-fields.json` (molde en `.dai/templates/`) y reintenta.
+5. **Estado.** Dejar la US en `pulida`. Ofrecer que el dev siga con `dai link-us <ID>` → `opsx:propose` (lado técnico).
 
 ## Hand-off
 

package/skills/link-us/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: link-us
-description: Del lado del dev — crea la branch desde el link de la User Story en Jira SIN margen de error y genera el archivo implements.yaml con el link a la US (id + version + ac_hash). Es la que hace que el link QUÉ↔CÓMO sea correcto por construcción, sin que el dev tipee el key a mano. Invocar como /link-us ABC-### (o con la URL del ticket de Jira). Usar al arrancar la implementación de una US, antes o junto con opsx:explore / opsx:propose.
+description: "Del lado del dev — crea la branch desde el link de la User Story en Jira SIN margen de error y genera el archivo implements.yaml con el link a la US (id + version + ac_hash). Es la que hace que el link QUÉ↔CÓMO sea correcto por construcción, sin que el dev tipee el key a mano. Invocar como /link-us ABC-### (o con la URL del ticket de Jira). Usar al arrancar la implementación de una US, antes o junto con opsx:explore / opsx:propose."
 ---
 
 # link-us

package/skills/tdd/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tdd
-description: Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.
+description: "Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions \"red-green-refactor\", wants integration tests, or asks for test-first development."
 ---
 
 # Test-Driven Development

package/templates/jira-fields.example.json

@@ -0,0 +1,49 @@
+{
+  "_comentario": [
+    "Molde de .dai/jira-fields.json — los campos PROPIOS que tu Jira exige al crear un issue.",
+    "Copialo a .dai/jira-fields.json y ajustalo. Si tu Jira no exige campos propios, no lo",
+    "necesitás: sin archivo, dai publica igual que siempre (ADR-0015).",
+    "",
+    "Se declara por issuetype porque los campos obligatorios de una Story y de una Epic casi",
+    "nunca son los mismos. Un campo declarado TIENE que resolver a un valor (por 'default' o",
+    "por --field): se declara porque Jira lo exige. Si es opcional, no lo declares.",
+    "",
+    "  field    el id de Jira (requerido). Lo ves en la URL al editar el campo, o te lo dice",
+    "           el error 400 de Jira cuando falta.",
+    "  shape    cómo se envuelve el valor para la API:",
+    "             select → {\"value\": X}      un desplegable (el caso típico)",
+    "             text   → X                 texto plano",
+    "             multi  → [{\"value\": X}]    lista (el valor se parte por comas)",
+    "             raw    → JSON tal cual     escape hatch para cualquier forma rara",
+    "           Si lo omitís: con 'options' es select; sin 'options', text.",
+    "  default  el valor si no pasás --field. Omitilo cuando el valor cambia SIEMPRE según",
+    "           la US: así dai te lo pide en vez de inventar uno.",
+    "  options  los valores válidos. dai los valida ANTES de llamar a Jira: un typo da un",
+    "           error local con la lista, no un 400 críptico.",
+    "",
+    "Uso:",
+    "  dai publish us.md                                 (usa los defaults)",
+    "  dai publish us.md --field clasificacion=Corrección",
+    "  dai publish us.md --parent PROJ-42            (la cuelga de su épica)",
+    "  dai publish epica.md --issuetype Epic --field clasificacion=Mejora",
+    "",
+    "Verificá que parsee con:  dai doctor"
+  ],
+
+  "Story": {
+    "clasificacion": {
+      "field": "customfield_10042",
+      "shape": "select",
+      "default": "Mejora",
+      "options": ["Mejora", "Corrección"]
+    }
+  },
+
+  "Epic": {
+    "clasificacion": {
+      "field": "customfield_10042",
+      "shape": "select",
+      "options": ["Mejora", "Corrección"]
+    }
+  }
+}

package/templates/skill.md

@@ -0,0 +1,49 @@
+<!--
+  MOLDE DE SKILL · dai
+  ─────────────────────────────────────────────────────────────────
+  Formato: Agent Skills (SKILL.md) — un estándar abierto que leen Claude, Copilot y
+  Cursor. dai lo INGIERE y lo distribuye a los 3 (Claude y Copilot copia cruda · Cursor
+  `skillToCursor`), con `dai skills install --from <repo|path>` (ADR-0013 · ADR-0014).
+
+  Estructura del repo/dir fuente:
+      skills/
+        <nombre-de-la-skill>/
+          SKILL.md            ← este archivo (renombrado a SKILL.md, en MAYÚSCULAS)
+          <recursos...>       ← opcional: scripts, plantillas, refs que la skill use
+
+  CONTRATO MÍNIMO que dai valida (si falta, la salta con un warn):
+    - frontmatter con `name` y `description` (ambos obligatorios, en una línea).
+    - `name`: slug en kebab-case, IGUAL al nombre del directorio.
+    - `description`: una frase — con esto el agente decide CUÁNDO usar la skill.
+    - ambos, YAML VÁLIDO. Ojo: los asistentes parsean el frontmatter con YAML de
+      verdad, y un `: ` (dos puntos + espacio) suelto en la descripción hace que YAML
+      la lea como un mapa y DESCARTE LA SKILL ENTERA. Por eso la descripción va
+      SIEMPRE entre comillas dobles: te deja escribir la frase que quieras.
+
+  dai NO valida el CONTENIDO (qué dice la skill, qué hacen sus scripts): eso es
+  criterio del equipo. Las instalás bajo tu propio riesgo.
+-->
+---
+name: mi-skill
+description: "Qué hace la skill y cuándo conviene invocarla: concreto y orientado al disparador. Las comillas dobles no son decorativas — sin ellas, un ': ' rompe el YAML."
+---
+
+# <Título de la skill>
+
+Instrucciones para el agente: qué hacer, paso a paso. El **cuerpo es el mismo** para
+Claude, Cursor y Copilot — dai solo ajusta el frontmatter por asistente.
+
+## Cuándo usarla
+
+El disparador concreto (qué pide el usuario, o qué situación la activa).
+
+## Pasos
+
+1. …
+2. …
+3. …
+
+## Notas
+
+Convenciones del stack, ejemplos, o límites de la skill. Si necesita archivos de
+apoyo, ponelos junto al `SKILL.md` y referencialos por ruta relativa.