Módulo 2.3 - Instalación y configuración

📋 Requisitos previos

Antes de ejecutar cualquier comando, asegúrate de que tu máquina tenga el entorno adecuado. Las skills de Matt Pocock se ejecutan sobre runtimes que dan por sentadas cosas específicas; omitir este paso es el motivo #1 de que la instalación falle con un mensaje críptico.

🎯 Lo esencial en 3 puntos

• Claude Code (claude.com/claude-code) o Codex CLI instalado y con sesión iniciada.
• Node.js 18+ en el PATH — usado por npx que descarga el instalador.
• Uno repositorio de trabajo abierto (o carpeta nueva): el instalador escribe en .claude/ e docs/agents/.

✓ Configuraciones compatibles

✓Claude Code (escritorio o terminal): modo plugin
✓Codex CLI — modo archivo (skills/ en el repo)
✓macOS, Linux, WSL2 (Windows nativo a través de WSL)
✓Node 18 LTS, 20 LTS, 22 LTS
✓Repos con Git (recomendado) o carpetas sueltas
✓Issue trackers: GitHub, Linear, local (.scratch/)

✗ No compatible (todavía)

✗Windows nativo sin WSL: las rutas se rompen
✗Node 16 o anterior — npx incompatible
✗Jira, GitLab Issues, Notion (planificado, aún no está listo)
✗Editores como Cursor/Continue (la skill es para Claude/Codex)
✗Sin permiso de escritura en el proyecto (montajes de solo lectura)
✗Empresas que bloquean npm registry (sin proxy)

💡 Verificación rápida (10 segundos)

# Pega en la terminal antes de continuar: node --version # debe devolver v18+ claude --version # o: codex --version git estado # debe estar dentro de un repo

Si algo falla, resuélvelo antes de ejecutar el instalador. La mayoría de los bugs reportados se deben a requisitos previos faltantes.

📦 Instalación vía skills.sh (recomendado)

O skills.sh es el camino oficial. Un comando, sin clonar el repo ni editar JSON a mano. Detecta el runtime (Claude Code o Codex), copia los archivos correctos en el lugar indicado y abre una pantalla de selección.

# En la raíz del proyecto donde quieres usar las skills: npx skills@latest add mattpocock/skills

🔧 Qué hace el instalador internamente

1.Descarga el paquete skills vía npx (no se instala globalmente).
2.Detecta si estás en Claude Code (busca .claude/) o Codex (busca .codex/).
3.Haz git clone --depth 1 de mattpocock/skills en una caché temporal.
4.Lista de skills disponibles (engineering/, productivity/, misc/) con casillas de verificación.
5.Copia las elegidas a .claude/skills/ (o equivalente de Codex).
6.Registra las skills en el plugin.json o en la configuración local.

No modifica nada fuera de estos dos directorios. Es reversible: al borrar la carpeta de skills, vuelves al estado original.

🎛️ Seleccionando skills en el instalador

Después de ejecutar el comando, el instalador entra en modo interactivo. 4 pasos visuales hasta confirmar: no puedes equivocarte si sigues la pantalla. Lo más importante: marcar /setup-matt-pocock-skills en esta etapa, porque es quien va a configurar todo después.

Ejecutar el comando

Terminal abierto en la raíz del repo

Escribes npx skills@latest add mattpocock/skills. O npx descarga el instalador (~300KB) y se ejecuta en ~5 segundos la primera vez.

Salida esperada: "Fetching mattpocock/skills..." seguido de "Detected runtime: claude-code".

Aparece la pantalla de selección

Lista interactiva con casillas de verificación

Ves todas las skills agrupadas por bucket: engineering/ (handoff, ica, grill-me…), productivity/ (setup-matt-pocock-skills, triage-issues…), misc/. Usa las flechas para navegar y la barra espaciadora para marcar.

Skills personal/, in-progress/ e deprecated/ no aparecen — protege al usuario de los borradores.

Elegir agentes — marcar /setup-matt-pocock-skills

Etapa crítica — no saltar

Marca /setup-matt-pocock-skills obligatoriamente. Este agente se ejecuta una vez después de la instalación y genera los archivos de configuración (labels, paths de docs, integración con issue tracker). Sin él, las otras skills funcionan, pero desconectadas de tu flujo.

Recomendación mínima: /setup-matt-pocock-skills, /grill-me, /handoff. Después agregas el resto.

Confirmar y ver el diff

Todo escrito de una vez, atómico

Presionas Enter. El instalador muestra un resumen: "5 skills installed → .claude/skills/". Si usas Git, haz git status para ver todo lo que se agregó. Se recomienda hacer commit de inmediato como "chore: install matt-pocock skills".

Si algo sale mal a mitad del proceso, el instalador no deja el estado a medias: o se instala todo o no se instala nada.

🪄 Ejecutando /setup-matt-pocock-skills

Con las skills instaladas, abre Claude Code (o Codex) dentro del mismo proyecto y activa el agente de configuración. Él hace una entrevista breve (3-4 preguntas) y genera los archivos de configuración en el formato adecuado para tu flujo.

# En el prompt de Claude Code: /setup-matt-pocock-skills Agent: Voy a configurar tus skills. Tres preguntas rápidas. Agent: 1) ¿Qué issue tracker usas? a) GitHub Issues b) Linear c) Local (.scratch/ en el repo) You: a Agent: 2) Repo: "mi-org/mi-app"? (lo detecté en git remote) You: sí Agent: 3) ¿Qué labels usa el equipo para el triage? (escríbelas separadas por comas, o presiona enter para usar los valores predeterminados) You: bug, enhancement, question, docs Agent: 4) ¿Dónde debo guardar los docs de agentes? Predeterminado: docs/agents/ — ¿confirmas? (y/n) You: y Agent: Configurando... - Creando docs/agents/triage-labels.md - Creando docs/agents/issue-tracker.md - Actualizando .claude/skills/triage-issues/config.json Agent: Listo. Prueba con /grill-me o /triage-issues.

💡 Recomendaciones según el tamaño del equipo

En solitario / proyecto paralelo: issue tracker local (.scratch/). Sin fricción, sin dependencias externas.
Equipo pequeño (2-5 desarrolladores): GitHub Issues. Es donde ya vive el código y todos tienen acceso.
Equipo mediano/grande (6+): Linear si la empresa ya lo paga. De lo contrario, GitHub Projects.
Empresa regulada/cerrada: local + sincronización manual. Evita exponer decisiones internas en un SaaS público.

🗂️ Configuración del gestor de issues

La elección del issue tracker da forma al resto del flujo. Skills como /triage-issues e /handoff necesitan saber dónde crear o leer tickets. Los tres modos cubren el 95% de los casos.

✓ Cuándo usar cada uno

GitHub Issues — repo público/privado, todo el equipo tiene acceso, se integra con PRs.
Linear — organización paga Linear, quiere ciclos/proyectos estructurados.
Local (.scratch/) — individual, offline, exploratorio. Sin costo, sin auth.

✗ Cuándo NO usarlo

GitHub — si el repo es cerrado pero el tracker debe ser cross-repo.
Linear — si estás solo o todavía estás validando la idea (overkill).
Local — en equipos de 3+ personas (cada una tendrá un .scratch/ diferente, sin sincronización).

La configuración generada vive en docs/agents/issue-tracker.md. Ejemplo generado por la configuración inicial cuando eliges GitHub:

# docs/agents/issue-tracker.md tracker: github repo: mi-org/mi-app default_assignee: "@me" auth: gh-cli # usa `gh auth status` p/ verificar queries: open_bugs: "is:open label:bug" needs_triage: "is:open no:label" my_work: "is:open assignee:@me" create_template: body_prefix: "" add_labels_on_create: ["triage"]

🏷️ Etiquetas de triage

Las labels son el vocabulario que une a las personas y los agentes. Si dices "esto es un bug" y el agente dice "esto es un defecto", ustedes duplican tickets. El setup genera un mapeo papel → label string para estandarizar.

Cada papel semántico (lo que representa el ticket en el flujo) se convierte en una cadena canónica. Cambias las cadenas para reflejar el vocabulario de tu equipo, pero mantienes los roles:

# docs/agents/triage-labels.md labels: # --- función: tipo de problema --- bug: "bug" # defecto en el comportamiento existente feature: "enhancement" # solicitud de nuevo comportamiento docs: "docs" # mejora de documentación question: "question" # duda, todavía no se puede accionar # --- función: estado en el flujo --- needs_triage: "triage" # llegó y todavía no se evaluó blocked: "blocked" # esperando algo externo ready: "ready" # priorizado y se puede tomar # --- función: prioridad --- p0: "priority:p0" # incidente, detener todo p1: "priority:p1" # prioritario en el sprint p2: "priority:p2" # cuando se pueda color_hints: bug: "#d73a4a" enhancement: "#a2eeef" docs: "#0075ca"

📊 ¿Por qué mapear rol -> string?

Porque el nombre interno (bug) es estable en el código del agente, pero la cadena visible para el usuario ("defeito", "erro", "bug") varía entre equipos.

¿Renombraste la etiqueta en GitHub? Edita una línea aquí. El agente seguirá funcionando. Sin esta indirección, rompes todos los prompts cada vez que el equipo cambia el vocabulario.

🔧 Instalación manual (sin skills.sh)

Si tu empresa bloquea npm registry, o quieres control total sobre lo que entra en el repo, se puede hacer todo a mano. Requiere más trabajo, pero funciona en cualquier entorno.

# 1) Clonar el repo de skills en una ubicación separada git clone https://github.com/mattpocock/skills.git ~/src/mp-skills # 2) Crear un directorio de skills en tu proyecto (si no existe) mkdir -p .claude/skills # 3) Enlace simbólico (recomendado — recibe actualizaciones con git pull) ln -s ~/src/mp-skills/skills/engineering/grill-me .claude/skills/grill-me ln -s ~/src/mp-skills/skills/engineering/handoff .claude/skills/handoff ln -s ~/src/mp-skills/skills/productivity/setup-matt-pocock-skills .claude/skills/setup # 4) O copia (snapshot, no recibe actualizaciones) cp -r ~/src/mp-skills/skills/engineering/grill-me .claude/skills/ # 5) Registrar en plugin.json (si corresponde a tu configuración) cat .claude/plugin.json # agrega las skills al array "skills": [...] # 6) Reiniciar Claude Code para cargarlo claude restart

🧭 Symlink vs copia

Symlink: uno git pull en el clone actualiza todo. Ideal para ti si siempre quieres lo último.
Copia: congela la versión. Bueno para equipos que necesitan una skill estable y revisión por PR.

Después de esta configuración manual, todavía tienes que ejecutar /setup-matt-pocock-skills dentro de Claude Code para generar los archivos de configuración. La instalación manual solo coloca los archivos en su lugar — la configuración es independiente.

✅ Verificando que todo funcione

Lo instalaste y configuraste; ahora demuestra que está funcionando. /grill-me es la prueba más rápida: hace que el agente pregunte sobre el problema actual en vez de responder directamente. Si se cargó esta skill, se cargaron todas.

# En Claude Code, dentro del proyecto: /grill-me quiero agregar autenticación a la app Agent: Antes de proponer código, déjame entender: 1. ¿Qué provider ya decidiste? (Auth0, Clerk, custom, NextAuth...) 2. ¿Web, mobile o ambos? 3. ¿Ya tienes usuarios en prod? (define migración vs. greenfield) 4. ¿Email/contraseña, social, magic link o combinación? 5. ¿Cuál es el requisito de sesión? (JWT, cookie, refresh tokens?) # Si aparece esto, está funcionando. Si el agente # responde directamente con código, la skill no se cargó.

📋 Lista de verificación

✓/grill-me <qualquer coisa> hace preguntas en vez de dar una respuesta directa
✓/handoff genera Markdown estructurado en vez de prosa suelta
✓Archivos docs/agents/issue-tracker.md e triage-labels.md existen
✓.claude/skills/ tiene las carpetas de las skills seleccionadas
✓git status muestra los archivos nuevos: listo para el commit
✓Reinició Claude Code una vez para garantizar que se leyeran los archivos

🩺 Solución de problemas

Casi todo lo que sale mal cae en tres categorías. Identifica el síntoma, aplica la corrección y sigue con tu vida.

✗ Síntomas comunes

La skill no aparece al escribir / — autocompletado vacío o solo con opciones integradas.
Conflicto con otra skill — dos skills con el mismo nombre o trigger, mensaje "ambiguous command".
El plugin no se carga — Claude Code se abre, pero ninguna skill personalizada funciona; hay un error en el registro de inicio.
El agente responde directamente sin ejecutar la skill — tú escribes /grill-me y solo responde como un chat normal.

✓ Soluciones

Reiniciar — 70% de los casos. Claude Code solo lee .claude/ en el startup.
Renombrar la skill conflictiva o deshabilitar la duplicada en el plugin.json.
Validar JSON — cat .claude/plugin.json | jq. Una coma final lo rompe todo.
Forzar el prefijo de una skill en el prompt: /grill-me tiene que ser la primera palabra del mensaje.

🛠️ Solución: la skill no aparece

Comprueba si el directorio existe: ls .claude/skills/grill-me.
Comprueba si hay SKILL.md adentro, con frontmatter válido (nombre, descripción).
Reinicia: cierra Claude Code por completo (no solo la ventana) y vuelve a abrirlo.
Si todavía no aparece, revisa los logs en ~/.claude/logs/ — busca "skill load error".
Última opción: elimina la carpeta de la skill, ejecuta npx skills@latest add de nuevo.

⚠️ Atención con los permisos

Si ejecutaste npx con sudo alguna vez, los archivos pueden haber quedado como root y Claude Code (que se ejecuta como tu usuario) no puede leerlos. Corrígelo con: sudo chown -R $USER .claude/. Nunca vuelve a ejecutar el instalador con sudo.

🎓 Resumen del módulo

✓

Requisitos previos — Claude Code (o Codex) + Node 18+ + repo con permiso de escritura. Sin eso, nada funciona.

✓

Instalación mediante skills.sh — npx skills@latest add mattpocock/skills. Un comando, copia archivos, registra el plugin y es reversible.

✓

4 pasos en el installer — ejecutar → pantalla → marcar /setup-matt-pocock-skills → confirmar.

✓

El setup te entrevista — issue tracker, labels, rutas de docs. Genera archivos versionables en docs/agents/.

✓

Etiquetas = rol -> string — una indirección que protege tus prompts cuando cambia el vocabulario del equipo.

✓

Lo verificaste con /grill-me — si hace preguntas en vez de responder directamente, todo sigue activo.

✓

Solución de problemas — 70% de los problemas se resuelven reiniciando Claude Code. El JSON inválido y los permisos cubren el resto.

Siguiente ruta:

Ruta 3 — Práctica: ejecutando skills reales en proyectos reales, /handoff entre sesiones, /grill-me en arquitectura, flujos avanzados de triage.

← Módulo 2.2 Ir a Trilha 3 →