--- type: SOP asset_id: SOP-EL-SkillsAlta-v02 version: v02 status: Superseded por SOP-EL-SkillsAlta-v03 (2026-07-11) — sigue válido como referencia del proceso manual y glosario owner: Victor Heredia sherpa_owner: Jay ratificador: Victor Heredia (L3+) fecha_creacion: 2026-06-18 fecha_ultima_actualizacion: 2026-07-07 intellbank: IB-EL-EmpowerLabs subbank: CP-EL-Control-Planes proposito: El ciclo de vida completo de una skill — crear, guardar, compartir y mantener el banco actualizado. Con la arquitectura corregida (marketplace FUERA del vault) y glosario. supersede: SOP-EL-SkillsAlta-v01 (v01 asumía el marketplace DENTRO del vault — causa raíz de la corrupción por sync; corregido en v02) relacionados: - CP-EL-SkillsRegistry-v01 (el banco / inventario) - MPB-EL-SkillsPlaybook-v01 (conceptos y tips por nivel) - TP-EL-PluginMarketplace-Handoff-v01 (publicación al equipo) - feedback_vault_sync_mangles_dotfiles (por qué el marketplace va fuera del vault) tags: [SOP, skills, ciclo-de-vida, crear, guardar, compartir, mantener, marketplace, plugin, glosario] --- # SOP · Ciclo de vida de una Skill ## Crear · Guardar · Compartir · Mantener — de la idea al equipo > **Regla raíz #1 (arquitectura):** el **marketplace** de plugins vive en su **propio repo git, > FUERA del vault** Intellibanks. NUNCA dentro del vault: la sincronización mutila los archivos > ocultos (`.claude-plugin`→`archivo.claude-plugin`, `plugin.json`→`plugin_json.md`) y rompe los > plugins. *(Ver glosario y `feedback_vault_sync_mangles_dotfiles`.)* > > **Regla raíz #2 (caché):** se edita la **FUENTE** (el repo git), nunca el **caché instalado** > (`.remote-plugins/`). Editar el caché rompe el descubrimiento de comandos. > > **Qué SÍ va en el vault:** el **banco/registry** y el playbook — son `.md` normales y > sincronizan bien. Solo los **plugins** (con dotfolders) se corrompen. --- ## Mapa del ciclo (4 fases) ``` 1. CREAR → detectar patrón · decidir tipo · generar · Gate G0 2. GUARDAR → colocar en la FUENTE (repo git fuera del vault) · subir versión 3. COMPARTIR → empaquetar (.plugin) · publicar (git push) · el equipo instala 4. MANTENER → actualizar · registrar en el banco · retirar lo viejo · verificar ``` --- # FASE 1 · CREAR ### 1.1 Detectar el candidato Un flujo que repites **≥3 veces** con la misma estructura es candidato a skill. ### 1.2 Decidir el tipo - **Skill** — dispara sola por su `description` (para capacidades que el modelo activa por contexto). - **Comando** (`/nombre`) — lo disparas tú explícitamente. - **SVA / UltraSherpaX** — súper asistente (shell × Brain Code); se produce con `ultrasherpax-generator`. ### 1.3 Decidir el plugin destino | Si es… | Plugin | |---|---| | Operación WORX del día a día | `worx-empowerlabs` | | Producto WikiX | `worx-wikix` | | Cognición / súper asistente (SVA) | `worx-ultrasherpas` | | Base org-agnóstica (individual) | `worx-core` | | Dominio nuevo que no encaja | **plugin nuevo** en el marketplace | ### 1.4 Gate G0 — ¿ya existe? Consulta `CP-EL-SkillsRegistry-v01` antes de crear. Si ya existe → versiónala, no dupliques. ### 1.5 Generar Motor según el tipo: `skill-creator` (genéricas) · `ultrasherpax-generator` (SVAs) · `brain-code-distiller` (Brain Codes) · o escribes el `.md` del comando a mano. **La `description` es el disparador** — inclúyele las frases reales que diría el usuario. Mantén el `SKILL.md` corto; el detalle pesado va en `references/`. --- # FASE 2 · GUARDAR ### 2.1 Colocar en la FUENTE Copia la skill/comando a la carpeta de su plugin **en el repo git del marketplace** (fuera del vault): - Skill → `/skills//SKILL.md` (+ `references/`). - Comando → `/commands/.md`. ### 2.2 Subir la versión del plugin En `/.claude-plugin/plugin.json`, sube `version` (semver: parche/menor/mayor). **El bump de versión es lo que dispara la actualización** en las máquinas del equipo. ### 2.3 Actualizar el README del plugin Tabla de comandos/skills + `keywords` si aplica. > ❌ **Nunca** guardes plugins dentro de Intellibanks. ❌ Nunca edites `.remote-plugins/`. --- # FASE 3 · COMPARTIR ### 3.1 Empaquetar - **Un plugin** → un archivo **`.plugin`** (zip con **exactamente 1** `plugin.json`). - **Todo el marketplace** → el repo git completo (o un zip del repo, para moverlo). ### 3.2 Publicar (vía canónica: git) `git push` del repo del marketplace al remoto privado de EmpowerLabs. El equipo: ``` /plugin marketplace add /empowerlabs-plugins /plugin install @empowerlabs ``` o **auto-instala** pegando `team-settings.json` en el `.claude/settings.json` del repo de trabajo (`autoUpdate: true`). ### 3.3 Vía interina (mientras el git no está listo): Google Drive Puente válido **solo para los ZIP**: - Sube los `.plugin` **zippeados** a una carpeta de Drive. **Nunca descomprimas ahí** — Drive Desktop mutila los dotfolders igual que la sync del vault. - Cada persona descarga el `.plugin` e instala por el botón "instalar plugin" (pide 1 `plugin.json` → por eso los `.plugin` individuales, **no** el zip del marketplace). - Sin auto-update: cada cambio = re-subir el zip nuevo. --- # FASE 4 · MANTENER ### 4.1 Actualizar una skill Editas la FUENTE → subes `version` → `git push` → el equipo corre `/plugin update` (o entra solo con `autoUpdate`). ### 4.2 Registrar en el BANCO (esto es "mantener el banco actualizado") - **Registry** `CP-EL-SkillsRegistry-v01` — agrega/actualiza la entrada en su bloque. Sube el conteo. - **Dashboard** `VIZ-EL-SkillsRegistry-Dashboard-v01` — añade el objeto a `DATA`. - Registro maestro (si es activo canónico) → `CP-XX-IntelliBanks-Registry` con `bmf-registry-updater`. ### 4.3 Retirar lo viejo Cuando reemplaces o renombres una skill/plugin, **desinstala la versión vieja del caché** (`.remote-plugins/`). Si la dejas, sigue corriendo y puede recrear carpetas/rutas obsoletas. ### 4.4 Verificar (sesión nueva) La skill/comando aparece y **dispara**; `/arrancaroom` sigue intacto; el registry refleja lo instalado. ### 4.5 Ritmo Cierre de semana: verificar que el registry = lo instalado; correr health checks. --- ## Conceptos + estructura del plugin **Los tres, sin confundir** (definiciones completas en el Glosario): - **Plugin** = la caja que instalas (agrupa comandos + skills). Ej: `worx-empowerlabs`. - **Comando** (`/nombre`) = acción que **tú** disparas. Vive en `commands/`. Ej: `/wx-arrancaroom`. - **Skill** = capacidad que **dispara sola** por su `description`. Vive en `skills/`. Ej: `wx-buzon`. > *Comando = ritual que inicias tú · skill = capacidad que salta sola por contexto.* **La anatomía que TODO plugin debe tener:** ``` / ├── .claude-plugin/ │ └── plugin.json ← manifiesto (name · version · description · author · keywords). ÚNICO archivo aquí. ├── commands/ │ └── .md ← un archivo = un /comando (frontmatter `description:` + cuerpo) ├── skills/ │ └── / │ ├── SKILL.md ← frontmatter (name + description) + instrucciones │ └── references/ ← opcional: detalle pesado, se lee SOLO si hace falta └── README.md ``` - Solo `plugin.json` va en `.claude-plugin/`. `commands/` y `skills/` en la **raíz** del plugin. - El plugin vive en el **repo git** (fuera del vault). Nombres propios: `/wx-` (producto) o `/sk-` (interno). --- ## Recomendaciones de eficiencia (tokens) al escribir skills El `SKILL.md` se carga **entero** cada vez que dispara — cada línea se paga en **cada** invocación. 1. **Corto por diseño.** Detalle pesado → `references/` (se lee solo cuando hace falta), no en el cuerpo. 2. **`description` = disparador, no resumen.** Precisa, con las frases reales del usuario. 3. **Imperativo y terso.** "Haz X" > "Deberías considerar…". Cero relleno. 4. **No repitas contexto** que el SherpaX ya tiene (reglas WORX, identidad). Referéncialo. 5. **Tablas/bullets > prosa.** Más denso y escaneable. 6. **Referencia por ruta, no inline.** "Lee `X-v01.md`" > pegar su contenido. 7. **Un skill = un trabajo.** No metas 3 capacidades en una (ej: el buzón NO va en el skill de contexto). 8. **Determinista → script.** Apunta a un `.js`/`.py` en vez de describir pasos re-ejecutables. 9. **Cierra con la acción concreta.** > **Regla mental:** el cuerpo del `SKILL.md` se paga en cada disparo; `references/` solo cuando se lee. Pon en el cuerpo lo que **siempre** se necesita; el resto abajo. --- ## Checklist de alta (copia y marca) - [ ] F1 · Tipo + plugin destino decididos · Gate G0 (no duplica) · `description` con frases-disparador - [ ] F2 · En la FUENTE (repo git, fuera del vault) · `version` subida · README - [ ] F3 · Empaquetado `.plugin` (1 plugin.json) · publicado (git push o Drive interino) - [ ] F4 · Registrado en registry + dashboard · viejo retirado · verificado en sesión nueva ## Anti-patrones (lo que rompe el sistema) - ❌ Guardar el marketplace/plugins **dentro del vault** → la sync los corrompe. - ❌ Editar el caché `.remote-plugins/` a mano → rompe el discovery. - ❌ Subir el **zip del marketplace** al instalador de UN plugin → "Found 2 plugin.json". Usa el `.plugin` individual. - ❌ Descomprimir plugins en Google Drive → mutila dotfolders. - ❌ Olvidar subir `version` → el equipo no recibe la actualización. - ❌ Olvidar registrar en el banco → la skill existe pero el banco no la conoce. - ❌ `description` pobre → la skill nunca dispara (o dispara de más). --- ## GLOSARIO (para que todos entiendan los términos) | Término | Qué es, en simple | |---|---| | **Skill** | Una capacidad empaquetada que el SherpaX activa **sola** cuando tu mensaje la dispara (por su `description`). Ej. `brain-code-distiller`. | | **Comando (slash command)** | Una acción que **tú** disparas escribiendo `/nombre`. Ej. `/arrancaroom`. | | **Plugin** | Un **paquete** que agrupa skills y/o comandos + su manifiesto. Es la unidad que instalas. Ej. `worx-wikix`. | | **plugin.json** | El **manifiesto de UN plugin**: su nombre, versión y descripción. Vive en `/.claude-plugin/plugin.json`. | | **marketplace** | La **"tienda"/catálogo** que agrupa VARIOS plugins. Técnicamente es un **repo git** con un `marketplace.json`. De ahí el equipo instala y actualiza. | | **marketplace.json** | El **índice** del marketplace: lista qué plugins contiene y dónde. | | **.plugin** | El **archivo (zip) de UN solo plugin**, listo para instalar por el botón. Debe tener **exactamente 1** `plugin.json`. | | **repo git** | Una carpeta **versionada** (ej. en GitHub) desde donde se publica y se actualiza. El marketplace vive aquí, **fuera del vault**. | | **git push** | Subir los cambios del repo al servidor (GitHub) para que el equipo los reciba. | | **caché instalado / `.remote-plugins/`** | La **copia local** que la app crea al instalar un plugin. Es **solo-lectura**: nunca se edita a mano. | | **version / semver** | El número de versión `MAYOR.MENOR.PARCHE` (ej. `0.2.0`). Subirlo es lo que **dispara la actualización** en el equipo. | | **autoUpdate** | Bandera en `settings.json` que hace que el equipo **reciba las actualizaciones solo**, sin instalar a mano. | | **registry / banco de skills** | El **inventario** de qué skills existen (`CP-EL-SkillsRegistry`). Vive en el vault (es un `.md`). No confundir con el marketplace (distribución). | | **vault** | El **almacén de conocimiento** (Intellibanks). Se sincroniza a la nube. | | **sync** | La **sincronización** del vault a la nube. Mutila archivos/carpetas ocultas → por eso el marketplace va **fuera**. | | **dotfolder / dotfile** | Carpeta/archivo cuyo nombre empieza con **punto** (ej. `.claude-plugin`). La sync los daña. | | **Gate G0 (Vault-First)** | Regla: **consulta el vault/registry antes** de producir algo nuevo (no duplicar, usar lo que existe). | | **description (frontmatter)** | El texto arriba del `SKILL.md` que **decide si la skill dispara**. Es lo más importante de una skill. | | **SKILL.md** | El archivo que **es** la skill: su `description` + las instrucciones. | | **SVA / UltraSherpaX** | **Súper asistente** = un especialista (shell) + la cognición de un Brain Code. Ej. `demand-gen-ultra`. | | **Brain Code (BC)** | La **cognición destilada** de una fuente (cómo piensa una persona/escuela/empresa). | | **shell** | El **especialista funcional base** (qué hace y cómo entrega), sin cognición profunda. Se fusiona con un Brain Code para hacer un SVA. | | **tripleta** | Los 3 roles de gobernanza de cada activo: **Owner + Sherpa + Ratificador**. | | **naming BMF** | La convención de nombres: `TIPO-ENTIDAD-Proyecto-Nombre-vNN`. | ## CHANGELOG | Versión | Fecha | Cambio | |---|---|---| | v01 | 2026-06-18 | Creación. 7 pasos + checklist + anti-patrones. Asumía marketplace dentro del vault. | | v02 | 2026-07-07 | Reescritura en 4 fases (Crear·Guardar·Compartir·Mantener). **Corrección raíz: marketplace FUERA del vault** (la sync corrompe dotfolders). Empaque `.plugin` vs zip del marketplace. Vía interina Google Drive. Fase de retiro de plugins viejos. **Glosario** de términos. Supersede v01. |