Contenido detallado
🧩 Tres capas, un orden
Este módulo cubre de una vez las tres capas de capacidad: Habilidades (capa 4), Herramientas (capa 5) y Agentes (capa 6). El siguiente te lleva por ellas en esta secuencia, y no es casualidad: un agente solo tiene sentido cuando hay skills que pueda orquestar, y las skills solo tienen sentido cuando hay un sustrato que puedan leer.
🌱 ¿Nuevo aquí?
Skill (en PT: habilidad) es un trabajo repetible escrito como una receta, para ejecutarlo igual cada vez. Herramienta es un cable que conecta el OS con una fuente de datos real (una base de datos, un calendario, una hoja de cálculo). Agente es un «trabajador» con un rol, que decide qué skills usar y en qué orden, y revisa antes de que algo salga.
Cómo leer: la capacidad crece de izquierda a derecha. El agente (cuadro ámbar) contiene las skills que orquesta y una puerta de revisión. Por eso va al final: sin skills dentro, no tiene nada que coordinar.
Por qué aprender
Porque el error nº1 de quienes están entusiasmados es saltar directamente a los agentes —la parte "divertida"— y crear un agente que no tiene ninguna skill para usar. Saber el orden te evita construir el techo antes que las paredes. Ganas capacidad real, capa por capa, en vez de una cáscara vacía.
Conceptos clave
🛠️ Skill = verbo conquistado (primero la más repetida)
La analogía del coach: una skill es una ficha de receta. Las primeras veces cocinas «a ojo»; después anotas la receta para que cualquiera pueda repetirla igual. Por eso tú logro una skill: haz el trabajo a mano algunas veces y solo entonces captura los pasos. El coach comienza por UNA skill: tu tarea más repetida.
Las preguntas que hace
¿Qué tarea repites?
"...y te gustaría que funcionara igual cada vez?" Esa es una candidata para la primera skill.
¿Cómo lo haces a mano?
"Muéstrame el paso a paso." De aquí salen los pasos de la receta.
¿Cómo sabes si quedó bien?
Se convierte en la línea «qué es un buen resultado»: el criterio de calidad de la skill.
⚠️ El error común
Intentar escribir diez skills de una vez, o escribir una skill para algo que tú nunca lo hizo a mano. Primero gana experiencia: haz el trabajo de verdad algunas veces y luego captúralo. Una skill es la foto de un proceso que ya funciona, no una suposición.
Por qué aprender
Porque empezar por la tarea más repetida ofrece el mayor retorno con el menor riesgo. Es la tarea que conoces de memoria, así que la receta queda precisa, y es la que más tiempo te ahorra después. Y el coach te recuerda que una skill nunca está «lista»: mejorarás la receta con cada uso.
Conceptos clave
📂 Anatomía de skills/<nome>/SKILL.md
Cuando respondes, el coach crea la carpeta skills/ y, dentro de ella, una subcarpeta por skill con un SKILL.md simple. Captura tres cosas: cuándo usar, los pasos e qué es un buen resultado. Nada de jerga: es tu receta, escrita para que puedas repetirla.
Recreación ilustrativa — skills/checar-prazos/SKILL.md
# Revisar plazos ## Cuándo usar Todas las mañanas, o cuando pregunte "¿qué vence?". ## Pasos 1. Leer el tracker en substrate/compendium.md. 2. Calcular los plazos a partir de cada fecha. 3. Enumerar lo que vence en 10 días y lo que ya está atrasado. ## Qué es un buen resultado Una lista breve, con fechas y días restantes, sin olvidar ningún plazo.
🌱 ¿Nuevo aquí?
En Claude Code, una habilidad suele convertirse en un slash command — un atajo que activas escribiendo /algo. O SKILL.md es el archivo de texto que describe esa skill: el harness lo lee y aprende a ejecutar esa receta cuando la invocas.
Por qué aprender
Porque el done-check de la capa es exactamente esto: un trabajo real y repetitivo, escrito como skill, con pasos claros y una línea de «buen resultado». Ver la anatomía te permite reconocer cuándo una skill está completa y cuándo todavía es solo una idea suelta.
Conceptos clave
🔌 Herramientas: el cable de solo lectura
La capa 5 conecta el OS con fuentes de datos reales. La analogía del coach es contundente: una herramienta es una ventana por la que el OS mira, no una llave de toda la casa. De forma predeterminada es solo lectura (solo lectura): puede leer, pero no puede modificar. Y ningún secreto (contraseña, clave) entra en la carpeta.
🌱 ¿Nuevo aquí?
Read-only (solo lectura) significa que la conexión puede ver los datos, pero no puede cambiar nada. API es la "toma" oficial de un servicio para que los programas se comuniquen con él; CLI es un comando de terminal que ejecutas; MCP es un conector listo entre la IA y una herramienta. El coach te ayuda a elegir el camino más simple para cada fuente.
Recreación ilustrativa — tools.md
# Tools # Cada fonte: pra quê, e nível de acesso. - Calendário — ler datas de entrega — só-leitura - Planilha — ler bookings — só-leitura - E-mail — rascunhar (não enviar) — só-leitura # Segredos (senhas/chaves) ficam FORA desta pasta.
✓ Patrón seguro
- ✓Solo lectura de forma predeterminada.
- ✓Secretos fuera de la carpeta.
- ✓Redacción solo donde realmente sea necesaria.
✗ El error común
- ✗Dar permisos de escritura en todo «por si acaso».
- ✗Guardar la contraseña dentro de la carpeta del OS.
- ✗Conectar fuentes que el objetivo no requiere.
Por qué aprender
Porque escribir en todo es el camino más corto hacia un daño irreversible. Solo lectura es la versión de "mirar por la ventana": el OS te da respuestas con datos reales sin el riesgo de desordenar la fuente. El done-check es directo: cada fuente que necesita el objetivo está listada con su nivel de acceso, y no hay ningún secreto en la carpeta.
Conceptos clave
🤖 Agente: rol con criterio + portón de revisión
La analogía que lo cierra todo: las skills son las herramientas de cocina; el agente es el chef que sabe cuál elegir y prueba el plato antes de que salga. Un agente es un rol con criterio: decide qué skills usar y en qué orden, y ejecuta una revisión obligatoria antes de que nada salga. El coach solo crea un agente para una rutina que tú ya lo hace manualmente hoy.
Cómo leer: la tarea entra, el chef encadena skills, pero no sale nada sin pasar por la puerta de revisión. Esa puerta es lo que hace que delegar sea seguro: no es el agente quien decide por su cuenta qué publica.
Recreación ilustrativa — agents/<nome>/AGENT.md
# Gerente de entregas ## Papel Cuidar pra nenhuma entrega de cliente atrasar. ## Skills que orquestra - checar-prazos - rascunhar-aviso ## Portão de revisão (obrigatório) Nada vai a um cliente sem você ler e aprovar primeiro.
✓ Un agente
- ✓Tiene UN papel claro.
- ✓Orquesta skills existentes.
- ✓Tiene una puerta de revisión obligatoria.
✗ Agente «todoterreno»
- ✗Quiere resolver diez roles a la vez.
- ✗Se construye antes de que exista una skill.
- ✗Deja que el trabajo salga sin revisión.
Por qué aprender
Porque el punto de revisión es lo que separa "una automatización útil" de "una automatización que asusta". Sin él, un agente podría enviar algo incorrecto a un cliente. Con él, delegas la coordinación, pero conservas la última palabra. El done-check: una rutina real, orquestada y con un punto de revisión claro.
Conceptos clave
🚦 No te saltes pasos (y el "not started" honesto)
Dos medidas de seguridad guían este módulo. La primera: nunca un agente antes de que existan las skills que orquestaría — no te empujan a construir el chef antes de tener las ollas. Segundo: si una capa aún no se aplica a tu objetivo, el coach la marca como no iniciado con un motivo de una línea, en vez de inventar trabajo inútil.
🧭 Cuándo marcar «not started»
- Herramientas — ¿Tu objetivo todavía solo lee archivos locales? Sin fuente externa, marca not started: "todavía no se necesita ninguna fuente externa".
- Agents — ¿Solo tienes una skill? No hay nada que orquestar. Not started: "vuelve cuando haya 2-3 skills que se puedan encadenar".
- La señal de honestidad: una línea con el motivo > una carpeta vacía que finge trabajo.
💡 Consejo práctico
"Capa vacía" no es un fracaso. Un OS honesto con 3 capas sólidas y 3 marcadas no iniciado vale más que un OS con 6 capas mediocres. El coach prefiere la verdad — y la auditoría del 4.6 también.
Por qué aprender
Porque la tentación de saltar al agente es el error n.º 1, y el honesto «not started» es el antídoto contra lo contrario: llenar el OS de capas falsas para que parezca completo. Juntos, ambos frenos mantienen real tu sistema: solo tiene lo que sirve al objetivo y en el orden que permite dar el siguiente paso.
Conceptos clave
✅ Done-checks + copy-run
Cada una de las tres capas tiene su verificación de finalización. Ejecutas /os-coach next una vez por capa, y el coach construye el artefacto y marca el estado en el memory.md.
Las tres comprobaciones de finalización
- ✓Skills: un trabajo real y repetitivo se convirtió en una skill con pasos claros y una línea de «buen resultado».
- ✓Herramientas: toda fuente que el objetivo necesita está incluida con su nivel de acceso, y no hay secretos en la carpeta.
- ✓Agents: una rutina real, orquestada, con un punto de revisión claro.
Objetivo: recorrer las tres capas de capacidad, una a la vez, dejando que el coach construya cada artefacto.
1) Abre la capa de Skills:
/os-coach next
Responde (cámbialo por los tuyos):
Tarefa que repito: <ex.: checar quais entregas vencem> À mão eu faço assim: <passo 1; passo 2; passo 3> Fica bom quando: <ex.: nenhuma data passa batida>
2) Vuelve a ejecutarlo para Tools; responde cuáles son las fuentes y el acceso:
/os-coach next
Fontes: <ex.: calendário e planilha de bookings> → só-leitura
3) Vuelve a ejecutarlo para Agents (solo si ya tienes skills encadenables):
/os-coach next Rotina que encadeio à mão: <ex.: checar prazos e rascunhar o aviso> Revisão antes de sair: <ex.: eu aprovo todo aviso a cliente>
Cómo verificar: confirma que existen skills/<nome>/SKILL.md e tools.md, y que el tools.md dice "solo lectura". Ejecuta /os-coach status: las capas que no se usan aparecen como no iniciado con un motivo, no como error.
Por qué aprender
Porque al final de este módulo tu OS tiene capacidad real: al menos una skill que se ejecuta igual, conexiones de solo lectura a los datos que necesita y, si tiene sentido, un agente con una puerta de revisión. Es el momento adecuado para detenerte y puntuar todo según el objetivo — lo que haces en el Módulo 4.6 con el audit.
Conceptos clave
✅ Resumen del módulo
Siguiente módulo:
4.6 — audit: puntuar según el objetivo 📊