@dforce2055/dai 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -3,6 +3,19 @@
 Formato basado en [Keep a Changelog](https://keepachangelog.com/). Versionado semver
 (ver `VERSION`).
 
+## [0.7.0] — 2026-07-14
+
+**dai es el distribuidor de skills de cualquier stack, sin opinar sobre su contenido.**
+
+### Agregado
+- `dai skills install` — namespace de skills (`dai install` queda como alias). Con
+  `--from <git-url|path>[#ref]` instala **skills externas** por-stack (.NET, Java,
+  Rust…) desde un repo git (público o privado por SSH) o un path local, convertidas
+  para los 3 asistentes (Claude/Cursor/Copilot).
+  Self-service, one-off, sin registro; `dai sync` no las toca ([ADR-0013](docs/adr/0013-skills-externas-install-from.md)).
+  Valida el contrato mínimo (`SKILL.md` con `name` + `description`) y saltea con aviso
+  las malformadas; molde en [`templates/skill.md`](templates/skill.md). No valida el contenido.
+
 ## [0.6.0] — 2026-07-12
 
 Self-update del CLI y blindaje de autoría del repo.
@@ -181,6 +194,7 @@ ClickUp y Jira Cloud.
 - Tests de las rutas de red (jira/clickup/forge) con `fetch` mockeado. Sin links rotos;
   `files` de npm sin tests ni secretos.
 
+[0.7.0]: https://github.com/dforce2055/dai/releases/tag/v0.7.0
 [0.6.0]: https://github.com/dforce2055/dai/releases/tag/v0.6.0
 [0.5.0]: https://github.com/dforce2055/dai/releases/tag/v0.5.0
 [0.4.0]: https://github.com/dforce2055/dai/releases/tag/v0.4.0

package/README.md

@@ -49,7 +49,7 @@ deja las skills disponibles:
 
 ```bash
 npm i -g @dforce2055/dai        # el CLI
-dai install                     # skills de IA → Claude y Cursor (global por defecto)
+dai skills install              # skills de IA → Claude y Cursor (global por defecto)
 ```
 
 Y después, en el chat del asistente, según lo que tengas:
@@ -157,8 +157,10 @@ flowchart TD
 | Comando | Qué hace |
 |---|---|
 | `dai init [<repo>]` | scaffolder interactivo del repo. Flags: `--for claude\|copilot\|both\|cursor\|all` (asistente, default `all`) · `--pm md\|jira\|clickup` (tracker) · `--openspec` |
-| `dai install [--global \| --local <repo>] [--force] [--dry-run] [--for claude\|cursor\|all]` | instala/actualiza skills de IA en Claude y/o Cursor (`--for all` por defecto). `--force` re-copia aunque ya existan. Ej: `dai install --local . --for cursor --force` · `dai install --global --for all --force` |
+| `dai skills install [--global \| --local <repo>] [--force] [--dry-run] [--for claude\|cursor\|all]` | instala/actualiza las skills de dai en Claude y/o Cursor (`--for all` por defecto). `--force` re-copia. Alias: **`dai install`**. Ej: `dai skills install --local . --for cursor --force` |
+| `dai skills install --from <git-url\|path>[#ref] [--for …]` | instala **skills externas** (por-stack: .NET, Java, …) desde un repo/dir, **convertidas para los 3 asistentes**. Self-service, one-off, sin registro; `dai sync` no las toca. Colisión con una skill de dai → salta ([ADR-0013](docs/adr/0013-skills-externas-install-from.md)). Ej: `dai skills install --from github.com/mi-org/net-skills` |
 | `dai sync [--dry-run] [--for <asistentes>]` | **refresca** skills, constitución, templates y PR template a la versión del CLI — **aditivo** (no pisa tu `CLAUDE.md`), no toca el `.env` ni OpenSpec. Detecta los asistentes del repo o pasás `--for`. `--dry-run` muestra qué cambiaría ([ADR-0010](docs/adr/0010-versionado-y-upgrade.md)) |
+| `dai upgrade [--check] [--dry-run]` · alias `dai update` | **actualiza el CLI global** a la última publicada (`npm i -g …@latest`) — self-update. **No toca el repo**: reporta el drift del scaffold pero deja el `dai sync` al mantenedor. `--check` solo informa · `--dry-run` muestra el comando ([ADR-0012](docs/adr/0012-upgrade-self-update-del-cli.md)) |
 | `dai publish <us.md>` | crea la US en el tracker (Jira/ClickUp/md) desde un `.md` y devuelve el key. Es el fallback del MCP para publicar sin el asistente |
 | `dai link-us <ID> [--us <md>]` | crea branch + `implements.yaml`; sin `--us` trae la US del tracker |
 | `dai link-us <ID> --resync` | re-estampa el `ac_hash` contra la US viva (tras un ⚠️ de check) |
@@ -173,12 +175,33 @@ flowchart TD
 | `dai doctor` · `dai docs <dest>` · `dai version` | diagnóstico del entorno (incluye **version-drift** del scaffold) · copiar la doc · versión (`dai version` avisa si tu repo quedó atrás) |
 
 > **🆕 Mantené tu repo al día — `dai sync`.** Las skills, la constitución y los templates son un
-> *caché derivable* del CLI. Cuando actualizás `dai` (`npm i -g @dforce2055/dai`), **`dai doctor` y
+> *caché derivable* del CLI. Cuando actualizás `dai` (`dai upgrade`), **`dai doctor` y
 > `dai version` te avisan solos** si tu scaffold quedó atrás — con color y un `⬆️` —, y **`dai sync`**
 > lo refresca: **aditivo** (conserva tu `CLAUDE.md` propio), sin tocar el `.env` ni OpenSpec. Probá sin
 > riesgo con `dai sync --dry-run`. El versionado es semver: patch/minor no rompen nada; solo un major
 > pediría migración. ([ADR-0010](docs/adr/0010-versionado-y-upgrade.md))
 
+> **🧩 Skills de cualquier stack — `dai skills install --from`.** Además de las skills de
+> dai, cada equipo suma las suyas (por-stack: .NET, Java, Rust…) desde su propio repo:
+> `dai skills install --from github.com/tu-org/net-skills`. dai las **convierte para los 3
+> asistentes** (Claude/Cursor/Copilot) e instala. **dai es el distribuidor de skills de
+> cualquier stack, sin opinar sobre su contenido** — self-service, sin registro; `dai sync`
+> sigue siendo solo de dai. ([ADR-0013](docs/adr/0013-skills-externas-install-from.md))
+>
+> La fuente puede ser **pública, privada (por SSH) o un path local**: dai no hace auth
+> propia, delega en git — **si podés `git clone` el repo, dai instala desde ahí**. Para
+> privados usá la forma SSH (`git@github.com:tu-org/net-skills.git`), consistente con el
+> modelo de auth de dai ([ADR-0007](docs/adr/0007-modelo-de-autenticacion.md)). Público =
+> cero fricción entre equipos/máquinas.
+>
+> **Cómo armar una skill que dai ingiera.** Cada skill es un directorio con un `SKILL.md`
+> en **formato Agent Skills de Claude**: frontmatter con **`name`** y **`description`**
+> (obligatorios) + el cuerpo con las instrucciones. dai **valida ese contrato**: si a un
+> `SKILL.md` le falta `name`/`description`, o un dir no tiene `SKILL.md`, lo **saltea con
+> un warn** (no instala una skill rota). El **contenido** no lo valida — bajo tu criterio.
+> Molde: [`templates/skill.md`](templates/skill.md) · ejemplos reales: las skills de dai
+> en [`skills/`](skills/).
+
 Skills (se invocan en el asistente): `/doc-to-backlog` · `/grill-intent` · `/grill-epic` · `/grill-user-story` · `/link-us` ·
 `/tdd` · `/dai-review`. Config del tracker (`md`\|`jira`\|`clickup`) y tokens: en `.env` —
 ver [`.env.example`](.env.example). Auth (SSH + tokens): [ADR-0007](docs/adr/0007-modelo-de-autenticacion.md).

package/VERSION

@@ -1 +1 @@
-0.6.0
+0.7.0

package/cli/dai.mjs

@@ -29,7 +29,8 @@ import { composePrBody, prTitle, forgeTool } from "./lib/pr.mjs";
 import { dirsEqual } from "./lib/fsutil.mjs";
 import { parseFlags, parseAssistants, isAssistantToken } from "./lib/args.mjs";
 import { versionDrift, planUpgrade } from "./lib/semver.mjs";
-import { skillToPrompt, skillToCursor, constitution, constitutionCursorRule, envFor, mergeEnv, upsertBlock, reconcileGitignore } from "./lib/bootstrap.mjs";
+import { parseSource } from "./lib/skills-source.mjs";
+import { skillToPrompt, skillToCursor, validateSkill, constitution, constitutionCursorRule, envFor, mergeEnv, upsertBlock, reconcileGitignore } from "./lib/bootstrap.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 
@@ -416,6 +417,7 @@ async function cmdPr(opts) {
 
 // ── install: skills → ~/.claude/skills o <repo>/.claude/skills ────────────────
 async function cmdInstall(opts) {
+  if (opts.from !== undefined) return cmdInstallFrom(opts);   // skills externas (ADR-0013)
   const skillsSrc = join(ROOT, "skills");
   const skills = readdirSync(skillsSrc).filter((n) => statSync(join(skillsSrc, n)).isDirectory());
   let want;
@@ -489,6 +491,89 @@ async function cmdInstall(opts) {
   if (rl) rl.close();
 }
 
+// ── skills install --from: skills EXTERNAS (por-stack) desde un repo/dir ───────
+// Self-service, one-off, sin registro ni sync (ADR-0013). Convierte cada skill
+// para los 3 asistentes y la instala en el repo. No pisa las skills built-in de
+// dai (colisión → warn + skip). `dai sync` NO las toca: es solo de dai.
+function cmdInstallFrom(opts) {
+  if (typeof opts.from !== "string" || !opts.from.trim())
+    fail("--from necesita una fuente: un git URL (github.com/org/skills[#ref]) o un path local", 2);
+  let want;
+  try { want = parseAssistants(typeof opts.for === "string" ? opts.for : "all"); }
+  catch (e) { fail(`--for ${e.message}`); }
+
+  let src;
+  try { src = parseSource(opts.from); } catch (e) { fail(`--from ${e.message}`, 2); }
+
+  // Resolver la fuente a un directorio local.
+  let root, tmp = null;
+  if (src.type === "git") {
+    tmp = mkdtempSync(join(tmpdir(), "dai-skills-"));
+    info(`clonando ${src.location}${src.ref ? " @ " + src.ref : ""} …`);
+    const args = ["clone", "--depth", "1"];
+    if (src.ref) args.push("--branch", src.ref);
+    args.push(src.location, tmp);
+    try { git(args); }
+    catch (e) { rmSync(tmp, { recursive: true, force: true }); fail(`no pude clonar la fuente: ${String(e.message).split("\n")[0]}`, 1); }
+    root = tmp;
+  } else {
+    root = src.location;
+    if (!existsSync(root)) fail(`no existe la fuente: ${root}`, 2);
+  }
+
+  const cleanup = () => { if (tmp) rmSync(tmp, { recursive: true, force: true }); };
+
+  // El dir de skills: <root>/skills, o <root> si ya contiene <name>/SKILL.md.
+  const skillsDir = existsSync(join(root, "skills")) ? join(root, "skills") : root;
+  let entries;
+  try {
+    entries = readdirSync(skillsDir).filter((n) => {
+      try { return statSync(join(skillsDir, n)).isDirectory(); } catch { return false; }
+    });
+  } catch { cleanup(); fail(`no pude leer la fuente: ${skillsDir}`, 2); }
+  if (entries.length === 0) { cleanup(); fail("la fuente no tiene directorios de skill", 2); }
+
+  // Destino: repo local (default cwd), o --local <repo> / --global.
+  const repo = opts.global ? homedir() : (typeof opts.local === "string" ? opts.local : process.cwd());
+  const builtins = new Set(readdirSync(join(ROOT, "skills")));
+  const forStr = ["claude", "copilot", "cursor"].filter((a) => want[a]).join("+");
+  info(`skills install --from ${opts.from}  ·  ${entries.length} candidata(s)  ·  asistentes: ${forStr}${opts.dryRun ? "  [dry-run]" : ""}`);
+
+  let installed = 0, skipped = 0;
+  for (const name of entries) {
+    const srcDir = join(skillsDir, name);
+    const skillPath = join(srcDir, "SKILL.md");
+    // Validación estructural (contrato mínimo, no contenido — ADR-0013).
+    if (!existsSync(skillPath)) { warn(`'${name}' no tiene SKILL.md — salto`); skipped++; continue; }
+    if (builtins.has(name)) { warn(`'${name}' choca con una skill de dai — salto (renombrala, p.ej. ${name}-<stack>)`); skipped++; continue; }
+    const md = readFileSync(skillPath, "utf8");
+    const bad = validateSkill(md);
+    if (bad) { warn(`'${name}' inválida: ${bad} — salto (ver templates/skill.md)`); skipped++; continue; }
+    if (opts.dryRun) { info(`[dry-run] ${name} → ${forStr}`); continue; }
+    if (want.claude) {
+      const t = join(repo, ".claude", "skills", name);
+      rmSync(t, { recursive: true, force: true }); mkdirSync(dirname(t), { recursive: true }); cpSync(srcDir, t, { recursive: true });
+    }
+    if (want.cursor) {
+      const t = join(repo, ".cursor", "skills", name);
+      rmSync(t, { recursive: true, force: true }); cpSync(srcDir, t, { recursive: true }); writeFileSync(join(t, "SKILL.md"), skillToCursor(md));
+    }
+    if (want.copilot) {
+      const pdir = join(repo, ".github", "prompts"); mkdirSync(pdir, { recursive: true });
+      writeFileSync(join(pdir, `${name}.prompt.md`), skillToPrompt(md));
+    }
+    ok(name); installed++;
+  }
+  cleanup();
+  if (opts.dryRun) { info("dry-run: nada escrito."); return; }
+  process.stdout.write("\n");
+  if (installed === 0) {
+    fail(`0 skills instaladas${skipped ? ` (${skipped} salteada(s))` : ""} — revisá el formato: cada skill es un dir con SKILL.md y frontmatter (name + description). Molde en templates/skill.md`, 1);
+  }
+  ok(`${installed} skill(s) externa(s) instalada(s)${skipped ? `, ${skipped} salteada(s)` : ""} desde ${opts.from}`);
+  warn("skills externas — bajo tu criterio: dai las convierte e instala, no las vetea ni las trackea. `dai sync` no las toca.");
+}
+
 // ── helpers de prompt interactivo ─────────────────────────────────────────────
 async function askMenu(rl, title, choices, def) {
   process.stdout.write(`\n  ${title}\n`);
@@ -935,7 +1020,11 @@ switch (cmd) {
   case "pr":      cmdPr(opts).catch((e) => fail(String(e.message))); break;
   case "done":    cmdDone(opts); break;
   case "archive": cmdArchive(pos[0], opts); break;
-  case "install": cmdInstall(opts).catch((e) => fail(String(e.message))); break;
+  case "install": cmdInstall(opts).catch((e) => fail(String(e.message))); break;   // alias de `dai skills install`
+  case "skills":
+    if (pos[0] === "install" || pos[0] === undefined) cmdInstall(opts).catch((e) => fail(String(e.message)));
+    else fail(`subcomando de skills desconocido: '${pos[0]}' (por ahora: install)`, 2);
+    break;
   case "init":    cmdInit(pos[0], opts).catch((e) => fail(String(e.message))); break;
   case "sync":    cmdSync(pos[0], opts); break;
   case "upgrade":
@@ -959,7 +1048,8 @@ switch (cmd) {
       "  pr [--assignee u] [--base b] [--draft] [--yes]   crea TU PR/MR precargada (muestra + confirma)\n" +
       "  forge comment <ref> --body-file <f> · forge pr <ref>   comentar/leer una PR ajena (github/gitlab)\n\n" +
       "Instalación:\n" +
-      "  install [--global | --local <repo>] [--force] [--dry-run] [--for <asistentes>]   skills → Claude/Cursor\n" +
+      "  skills install [--global | --local <repo>] [--force] [--dry-run] [--for <asistentes>]   instala las skills de dai (alias: `install`)\n" +
+      "  skills install --from <git-url|path>[#ref] [--for <asistentes>]   instala skills EXTERNAS (por-stack), convertidas para los 3 asistentes (ADR-0013)\n" +
       "  init [<repo>]                scaffolder interactivo del repo (asistente, gestor, OpenSpec)\n" +
       "       --for <asistentes>      claude|copilot|cursor (combinables con coma) · o both|all (default all)\n" +
       "                               ej: --for claude,cursor · --for copilot · --for all\n" +

package/cli/lib/bootstrap.mjs

@@ -14,6 +14,18 @@ export function parseFrontmatter(md) {
   return { name, description, body: m[2].trim() };
 }
 
+// Valida el contrato MÍNIMO de un SKILL.md para que dai lo ingiera y lo convierta a
+// los 3 asistentes (y para que Claude/Cursor/Copilot lo carguen): frontmatter con
+// `name` y `description`. Devuelve null si está OK, o un string con el motivo.
+// NO valida el contenido de la skill — eso es criterio del equipo (ADR-0013).
+export function validateSkill(md) {
+  const { name, description } = parseFrontmatter(md);
+  if (!name && !description) return "sin frontmatter (falta name y description)";
+  if (!name) return "falta 'name' en el frontmatter";
+  if (!description) return "falta 'description' en el frontmatter";
+  return null;
+}
+
 // Transforma un SKILL.md (Claude) en un prompt file de Copilot (.prompt.md).
 // Cambia el frontmatter; el cuerpo (la lógica) es el mismo.
 export function skillToPrompt(md) {

package/cli/lib/skills-source.mjs

@@ -0,0 +1,26 @@
+// dai · resolución de una fuente de skills externas (`dai skills install --from`).
+// Núcleo puro (sin fs ni red): clasifica el argumento en git URL o path local y
+// separa el ref (`#branch`/`#tag`). Ver ADR-0013.
+
+// Devuelve { type: 'git'|'path', location, ref }.
+//   git   → URL clonable. `host/org/repo` (sin esquema) se normaliza a https://.
+//   path  → ruta local (relativa o absoluta). El `ref` se ignora aguas abajo.
+//   ref   → lo que va después de '#', o null.
+export function parseSource(src) {
+  const raw = String(src ?? "").trim();
+  if (!raw) throw new Error("fuente vacía (pasá un git URL o un path)");
+
+  // Separar el ref (#branch/tag). El scp de git (git@host:org/repo) no usa '#'.
+  let ref = null, loc = raw;
+  const hash = raw.lastIndexOf("#");
+  if (hash > 0) { ref = raw.slice(hash + 1) || null; loc = raw.slice(0, hash); }
+
+  // Path local explícito (./ ../ / ~/).
+  if (/^(\.\.?\/|\/|~\/)/.test(loc)) return { type: "path", location: loc, ref };
+  // git por sintaxis de URL (https, ssh, scp git@host:…).
+  if (/^(https?:\/\/|ssh:\/\/|git@|[\w.-]+@)/.test(loc)) return { type: "git", location: loc, ref };
+  // host/org/repo (p.ej. github.com/org/skills) → git https.
+  if (/^[\w.-]+\.[\w.-]+\/.+/.test(loc)) return { type: "git", location: "https://" + loc, ref };
+  // Resto: path local relativo sin ./.
+  return { type: "path", location: loc, ref };
+}

package/docs/adr/0013-skills-externas-install-from.md

@@ -0,0 +1,56 @@
+# ADR-0013 — `dai skills install --from` (skills externas por-stack)
+
+- **Estado:** aceptado
+- **Fecha:** 2026-07-14
+- **Decide:** lead / arquitecto de la metodología
+
+## Contexto
+
+dai distribuye **sus** skills (las bundleadas: `grill-*`, `link-us`, `tdd`, …) e
+instala/convierte para Claude, Cursor y Copilot. Pero los equipos tienen skills
+**propias de su stack** (.NET, Java, Rust, …) que hoy no tienen lugar: o las copian
+a mano por repo (duplicación, sin conversión a los 3 asistentes), o las meten en el
+paquete dai — que **rompe el ADN**: dai es agnóstico del stack, opina solo en su
+dominio (trazabilidad/distribución), no sobre *qué* dicen tus skills.
+
+Falta una forma de que dai **convierta e instale** skills externas, sin volverse
+dueño ni gatekeeper de ellas.
+
+## Decisión
+
+Agregamos **`dai skills install --from <git-url|path>[#ref]`**: instala skills
+**externas** desde un repo/dir (con estructura `skills/<nombre>/SKILL.md`, la misma
+de dai), **convertidas para los 3 asistentes** (Claude copia · Cursor `skillToCursor`
+· Copilot `skillToPrompt` → `.github/prompts/`).
+
+- **`dai skills` es el namespace canónico** de las operaciones de skills, consistente
+  con `dai forge <verb>`. `dai skills install` (sin `--from`) instala las de dai;
+  **`dai install` queda como alias** silencioso (backward-compatible).
+- **Self-service, one-off, sin registro.** No hay autorización central ni persistencia:
+  no existe `.dai/sources`, dai **no lleva registro** de qué repos usan skills externas.
+  El equipo las suma **bajo su propio criterio**.
+- **`dai sync` NO las toca** — sigue siendo **solo** de las skills de dai. Si el equipo
+  actualiza sus skills, re-corre `--from`.
+- **Colisión** con una skill built-in de dai → **warn + skip** (no se pisa la
+  metodología; renombran, p. ej. `tdd-dotnet`).
+
+## Consecuencias
+
+- **Más fácil:** cada equipo suma sus skills por-stack sin tocar dai ni pedir permiso,
+  y las escribe **una vez** (dai las sirve a Claude/Cursor/Copilot). El namespace
+  `dai skills` deja lugar a crecer (`skills list`, …) sin comandos sueltos.
+- **Se acepta pagar:** es **one-off** (dai no mantiene esas skills al día; re-corrés
+  `--from`). **Sin registro** → dai no sabe qué repos tienen skills externas, a
+  propósito: cero gatekeeping, bajo riesgo del equipo. Las fuentes remotas dependen de
+  git/red, y la **auth se delega en git** (público sin más; privado por SSH o credential
+  helper — dai no autentica): *si podés `git clone` la fuente, dai instala desde ahí*.
+
+## Alternativas consideradas
+
+- **Persistido (`.dai/sources`) + integrado a `dai sync`** — descartado: obliga a dai a
+  **registrar y mantener** fuentes externas (gatekeeping que el equipo no quiere), y
+  acopla `dai sync` —que debe ser solo de dai— a repos ajenos.
+- **Meter las skills de stack en el paquete dai** — descartado: rompe el ADN (dai
+  agnóstico del stack).
+- **Comando suelto `dai install --from` sin namespace** — descartado: `dai skills <verb>`
+  es más claro y consistente con `dai forge <verb>`; `dai install` queda como alias.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dforce2055/dai",
-  "version": "0.6.0",
+  "version": "0.7.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/templates/skill.md

@@ -0,0 +1,45 @@
+<!--
+  MOLDE DE SKILL · dai
+  ─────────────────────────────────────────────────────────────────
+  Formato: Agent Skills de Claude (SKILL.md). dai lo INGIERE y lo convierte a los 3
+  asistentes (Claude copia · Cursor `skillToCursor` · Copilot `.prompt.md`), con
+  `dai skills install --from <repo|path>` (ADR-0013).
+
+  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.
+
+  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.
+---
+
+# <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.