Archivos SKILL.md y el ecosistema Cobrainer
Qué son los archivos SKILL.md, cómo escribirlos y cómo Cobrainer los genera, armoniza y gobierna en toda la organización — desde Job Architecture hasta playbooks para Agent.
Qué es un archivo SKILL.md
Un archivo SKILL.md es un documento markdown estructurado que define instrucciones paso a paso para una tarea o capacidad específica. Es el playbook operativo que un AI Agent lee antes de ejecutar una tarea.
Piensa en él como una instrucción de trabajo detallada — pero escrita para AI Agent en lugar de humanos. Le dice al Agent: qué es la tarea, cuándo dispararla, qué pasos seguir, qué herramientas usar, cuáles son los criterios de éxito y cómo manejar casos límite.
Los archivos SKILL.md son el puente entre conocimiento humano y ejecución por Agent. Codifican expertise organizacional en un formato que los sistemas AI pueden consumir y ejecutar.
Estructura de un archivo SKILL.md
Un archivo SKILL.md bien estructurado contiene estas secciones:
| Sección | Propósito | Ejemplo |
|---|---|---|
| Title | Nombre claro de la tarea | "Screen Candidates Against Role Profile" |
| Description | Resumen de un párrafo de qué hace el skill | "Puntúa aplicaciones de candidatos contra la skill matrix de un rol especificado..." |
| When to Use | Condiciones de disparo para el Agent | "Usar cuando un hiring manager solicita screening de candidatos para una requisición abierta" |
| Prerequisites | Qué debe ser cierto antes de ejecutar | "El perfil del rol existe en Cobrainer. El MCP server del ATS está conectado." |
| Steps | Instrucciones ordenadas que el Agent sigue | "1. Recuperar perfil de rol vía Cobrainer MCP. 2. Obtener lista de candidatos del ATS..." |
| Tools Required | MCP servers y herramientas que el Agent necesita | "Cobrainer MCP: get_role_profile. ATS MCP: search_candidates." |
| Success Criteria | Cómo verificar que la tarea se completó correctamente | "Shortlist de top 5 candidatos generada con razonamiento para cada uno." |
| Edge Cases | Qué hacer cuando las cosas salen mal | "Si menos de 5 candidatos coinciden, baja el umbral de proficiency 1 nivel..." |
| Quality Checks | Reglas de validación que el Agent aplica | "Todos los candidatos deben tener al menos 3 de 5 skills requeridas al proficiency target." |
Mejores prácticas para archivos SKILL.md
Una tarea, un archivo
Cada archivo SKILL.md cubre exactamente una tarea discreta. No un rol. No un proceso. Una tarea.
Un rol como "Senior Recruiter" puede implicar 15–20 tareas. Cada tarea tiene su propio archivo SKILL.md: "Screen Candidates", "Draft Requisition", "Conduct Reference Check", "Generate Offer Letter". El rol es un compuesto. Las tareas son atómicas.
Condiciones de disparo claras
El Agent necesita saber cuándo usar un skill. Disparos vagos ("cuando haga falta") llevan a mal uso. Disparos específicos ("cuando un hiring manager envía una solicitud de screening para una requisición abierta con al menos 10 aplicantes") llevan a ejecución fiable.
Criterios de éxito medibles
Cada archivo SKILL.md define qué es "hecho". No "los candidatos están screened" sino "se genera una shortlist rankeada de los top N candidatos, cada uno con puntuación de skill-match y razonamiento escrito, guardada en el ATS como screening report."
Control de versiones y ownership
Los archivos SKILL.md son documentos vivos. Necesitan control de versiones (quién cambió qué, cuándo), ownership (quién mantiene el archivo) y ciclos de revisión (¿siguen siendo precisas las instrucciones?).
Referencias cruzadas
Las tareas raramente existen aisladas. Un SKILL.md de "Screen Candidates" debe referenciar el de "Draft Requisition" (porque el screening depende de una requisición bien definida) y el de "Generate Shortlist Report" (porque el screening alimenta el reporting).
El problema: archivos SKILL.md dispersos y sin gobernanza
Hoy, cada empleado tech-savvy construye su propio setup de AI Agent. Crean carpetas en sus máquinas con proyectos individuales. Algunos han montado herramientas de orquestación. Muchos han escrito sus propios archivos SKILL.md — ad hoc, sin documentar, inconsistentes.
El resultado:
- Sin consistencia — la misma tarea se describe distinto entre equipos
- Sin gobernanza — nadie revisa o aprueba las instrucciones que siguen los Agent
- Sin reuse — cada persona reinventa la rueda
- Sin seguridad — los archivos SKILL.md pueden instruir a Agent a acceder a sistemas sin autorización
- Sin alineación — los archivos SKILL.md individuales no reflejan las definiciones de rol reales, requisitos de skill o reglas de cumplimiento de la organización
Es el mismo problema que las organizaciones tuvieron con las descripciones de puesto hace 20 años: cada manager escribía la suya, en su formato, con sus criterios. La Job Architecture lo resolvió. La gobernanza de SKILL.md necesita la misma solución.
El rol de Cobrainer: el ecosistema de gestión de SKILL.md
Cobrainer está en posición única para resolver esto — porque Cobrainer ya descompone cada rol en tareas, y cada tarea mapea a skills. Los archivos SKILL.md, en esencia, representan tareas de roles. La conexión es directa.
Generación: de Job Architecture a archivos SKILL.md
El flujo:
- Job Architecture define familias, clusters, roles, niveles
- Cada rol contiene una lista de tareas
- Cada tarea mapea a skills y niveles de proficiency
- Cobrainer genera un archivo SKILL.md por tarea — con pasos, requisitos de herramientas, criterios de éxito y casos límite
El archivo SKILL.md se deriva de la arquitectura. No lo inventa una persona — se calcula a partir de la estructura organizacional.
Armonización: una tarea, un SKILL.md, en todas partes
La misma tarea aparece en múltiples roles. "Conduct Stakeholder Interview" existe en roles de Business Analyst, Product Manager y UX Researcher. Sin armonización, cada equipo escribe un SKILL.md distinto para la misma tarea.
Cobrainer armoniza: un SKILL.md canónico por tarea. Si la tarea aparece en 5 roles, los 5 referencian el mismo archivo. Las variaciones (herramientas distintas, contextos distintos) se manejan con parámetros, no archivos separados.
Repositorio centralizado: no portátiles, una biblioteca gobernada
En lugar de archivos SKILL.md dispersos en máquinas y carpetas:
- Almacenamiento central — todos los SKILL.md viven en un repositorio gobernado
- Control de versiones — cada cambio rastreado, historial de diff completo, capacidad de rollback
- Control de acceso — quién puede leer, modificar y desplegar archivos SKILL.md
- Distribución — los Agent obtienen el último SKILL.md de la fuente central. Sin copias locales obsoletas.
Derivado de la estructura: cambios de arquitectura actualizan los SKILL.md
Cuando un rol cambia — nuevas tareas añadidas, skills actualizados, targets de proficiency ajustados — los archivos SKILL.md derivados de ese rol se actualizan automáticamente. La arquitectura es la única fuente de verdad. Los SKILL.md son artefactos downstream.
Reglas de gobernanza consistentes
Cada archivo SKILL.md generado por Cobrainer hereda reglas organizacionales:
- Reglas de seguridad — qué sistemas puede acceder el Agent, qué datos puede leer o escribir
- Reglas éticas — constraints de equidad, comprobaciones de sesgo, requisitos de humano en el bucle
- Personalidad de marca — tono de voz, estilo de comunicación, reglas de lenguaje
- Fuentes de datos — dónde obtiene información el Agent (solo MCP servers aprobados)
- Constraints de cumplimiento — GDPR, transparencia salarial, requisitos laborales
Estas reglas no están embebidas en archivos individuales — se aplican desde política organizacional, consistentemente, en todos los SKILL.md generados.
Los archivos SKILL.md como puente
Los archivos SKILL.md conectan dos mundos:
| Mundo | Qué contiene | Quién lo posee |
|---|---|---|
| Job Architecture | Roles, tareas, skills, niveles de proficiency, estructura organizacional | RRHH, Diseño Organizacional, Cobrainer |
| Operaciones de Agent | Playbooks, configuraciones de herramientas, reglas de ejecución, criterios de calidad | IT, Operaciones, Equipos AI |
Los archivos SKILL.md son la capa de traducción. Toman lo que la organización define (en la Job Architecture) y lo convierten en lo que los Agent ejecutan (en workflows operativos).
Cobrainer gestiona ambos lados — y la traducción entre ellos. Esto es lo que lo convierte en el ecosistema de gestión de archivos SKILL.md: no solo un generador, sino la capa de gobernanza, versionado, distribución y sincronización que mantiene las operaciones de Agent alineadas con el diseño organizacional.
¿Necesitas ayuda para construir tu Arquitectura de Puestos y Skills? Habla con nuestro equipo.
Habla con Hanns