Adaptar las skills a tu proyecto

Tienes las skills instaladas y quieres que hablen de tu proyecto: tus comandos, tu secuencia de implementación, tu manifiesto de versión. Una skill copiada sin adaptar ocupa presupuesto de carga y da instrucciones que no aplican. La entrevista de init escribe esa adaptación por ti.

Cuándo usarla

• Corriste init sin terminal interactiva, o con --sin-entrevista, y las skills quedaron con su texto genérico.
• Cambió algo que la entrevista pregunta: el comando de verificación, la secuencia de implementación, si trabajas con varios agentes en paralelo.
• Quieres instalar skills que no vinieron por defecto.

Si lo que falta es definir el producto —PRD, arquitectura, specs—, la entrevista no lo hace: es Arrancar un producto desde cero.

Antes de empezar

Necesitas una terminal interactiva. Sin ella, init no entrevista nunca, y --entrevista sale con un error en vez de quedarse esperando. Cuándo entrevista init por su cuenta:

El proyecto	Qué hace init
Sin documentación: sin AI-FIRST.md, sin AGENTS.md, sin nada en docs/	Entrevista sin preguntar
Ya documentado	Dice qué encontró y ofrece la entrevista; por defecto, la salta
Sin terminal interactiva, o con --sin-entrevista	No entrevista
Con --entrevista	Entrevista aunque el proyecto esté documentado

Paso a paso

1. Corre la entrevista. Desde la raíz del repo:

   npx @falcux/ai-first@latest init --entrevista

   init nunca sobreescribe: lo que ya existe se salta y se reporta. Correrlo otra vez sobre un repo inicializado es seguro.

2. Responde. Todas las preguntas traen un valor por defecto entre corchetes, y Enter lo acepta. Varios salen de tu repo: el nombre, los comandos de package.json, el manifiesto.

   Pregunta	Para qué sirve
   Nombre del proyecto	AI-FIRST.md
   Fase: exploración, MVP o producción	La lee quien abre el archivo; no cambia ninguna verificación
   Clase de producto: saas, landing, api, cli, movil	Decide qué skills se instalan y qué artefactos pide el arranque
   Forma del repositorio: único, monorepo, varios repos	El perfil, junto con la anterior
   Comando que decide que el proyecto está sano	Las skills que verifican
   Comando de tipos y de lint, si hay	protocolo-features y test-fix
   ¿Varios agentes en paralelo?	Si no, la división por agentes se retira de la skill de features
   Archivo que lleva el número de versión	version-bump
   Orden en que se implementa una feature	Las opciones dependen de la clase de producto
   Una confirmación por cada Zona Prohibida sugerida	El criterio es el costo de revertir un error ahí

3. Lee el reporte. Cada línea dice escrito, saltado o sugerido. Una skill cuyo bloque no cambió aparece como saltada, con la razón.

4. Revisa cada skill adaptada. La adaptación vive bajo el encabezado «Adaptación a tu proyecto» de cada SKILL.md, entre <!-- ai-first:inicio --> y <!-- ai-first:fin -->. Debajo, fuera de las marcas, sigue la lista genérica de la skill: lo que la entrevista no cubre se completa ahí, a mano. Puedes pedirle al agente que te diga qué falta:

   Lee la sección «Adaptación a tu proyecto» de cada skill en .agents/skills/.
   Para cada una, dime qué puntos de la lista genérica no responde el bloque
   que escribió init. No edites nada todavía.

5. Completa fuera de las marcas. Lo que agregues fuera sobrevive a la siguiente corrida; lo que edites dentro, no. Por ejemplo, los tests intocables de test-fix o quién firma el cierre del descubrimiento en protocolo-arranque.

Qué queda escrito

En cada skill, el bloque entre marcas. Sólo en las skills para las que la entrevista tiene algo que decir:

Skill	Qué recibe
protocolo-arranque	El perfil y la tabla de artefactos que le corresponden, con su template
protocolo-features	La secuencia elegida, los comandos, si hay agentes en paralelo y, sin interfaz, qué pasos no aplican
test-fix	Los comandos y cómo delegar la corrida
version-bump	El manifiesto, único sitio donde se escribe el número
protocolo-cambios	Dónde vive el cambio en curso y el comando de verificación; en monorepo o varios repos, cómo cuenta el flujo corto
protocolo-cierre	La tabla de documentos del proyecto y el comando de verificación; si no hay manifiesto, que el paso del bump no aplica
protocolo-ux, ux-writer, ux-audit, information-architecture	El perfil y los documentos de diseño, sólo si el producto tiene interfaz

i18n no recibe bloque: la entrevista no pregunta nada que le sirva.

En AI-FIRST.md, la fase y el perfil, cuando init crea el archivo. Si ya existía no lo toca, como a cualquier otro archivo: si el perfil cambió, se edita a mano.

Las skills del perfil que falten. Con entrevista, la selección por defecto deja de ser las cinco de siempre:

Clase de producto	Skills
saas, movil	Las cinco de base, protocolo-ux, ux-writer, ux-audit e information-architecture
landing	Las cinco de base, protocolo-ux, ux-writer y ux-audit
api, cli	Las cinco de base

A todas se suma protocolo-arranque. Las cinco de base son protocolo-features, protocolo-cambios, protocolo-cierre, version-bump y test-fix. Las que ya estaban se saltan enteras; el bloque se reescribe en todas las de la selección.

Instalar más skills

--skills elige cuáles instalar, separadas por comas, o todas:

npx @falcux/ai-first@latest init --skills ux-writer,i18n
npx @falcux/ai-first@latest init --skills todas

Un nombre que el paquete no trae detiene el comando antes de entrevistar, con la lista de las disponibles. El bloque de AGENTS.md se reescribe con lo que quedó instalado.

Las skills enlazadas no se adaptan

Con --enlazar, cada skill es un enlace simbólico a la carpeta skills/ del paquete en vez de una copia. Una skill enlazada nunca se adapta: escribir ahí cambiaría la fuente y no tu copia. El reporte la marca como sugerido y lo dice.

Nota

Si una skill del paquete choca con una tuya del mismo nombre, init salta la del paquete y no toca la tuya. Las tres salidas posibles están en Las 11 skills.

Qué vigila el detector

Las skills no son artefactos declarados, así que audit no las recorre. Sí recorre AGENTS.md, que init declara en artefactos: el check de artefacto huérfano (P2) verifica que existan las rutas y los nombres que menciona, incluidos los de la tabla de skills del bloque. Si borras una skill a mano, vuelve a correr init para que el bloque se reescriba con lo que de verdad hay. Ver Las cinco verificaciones.

Por qué funciona así

Las marcas son el manifiesto: separan lo que escribió la herramienta de lo que escribiste tú, y por eso init puede reescribir sin pisar nada. Qué es una skill, cómo nace de un protocolo y por qué se adapta a cada proyecto está en Skills, hooks y gestión de contexto.

Próximos pasos

ai-first initTodas las opciones del comando.

Las 11 skillsQué hace cada skill y cuándo se activa.

Arrancar un productoLo que la entrevista no hace: definir el producto.