Coding-Agent Development Format Reference

Alcance de consulta

Esta referencia reúne ejemplos de formatos de desarrollo para coding agents, consultados el 2026-11-09. Permite reconocer qué artefacto configura cada responsabilidad y dónde comprobar sus reglas. Los canónicos persistent-instructions, agent-skills, agent-profiles, lifecycle-hooks y agent-extension-packages conservan las definiciones.

Los fragmentos son ejemplos documentales. Revisar su sintaxis no demuestra que un cliente particular los descubra o ejecute. Antes de usarlos deben comprobarse versión, superficie, ubicación, configuración efectiva y política organizacional. Ningún ejemplo configura el runtime del Atlas.

Elegir el artefacto por su función

Necesidad	Artefacto	Evidencia necesaria
Mantener convenciones y comandos del repositorio	Instrucciones persistentes	El cliente cargó la guía con el scope esperado.
Reutilizar un procedimiento con recursos	Skill	Se descubrió, se seleccionó y produjo evidencia pertinente.
Definir un especialista y sus herramientas	Perfil o custom agent	El runtime aplicó la configuración al participante correcto.
Ejecutar una comprobación ante un evento	Hook	El evento ocurrió y el handler produjo el efecto esperado.
Distribuir componentes relacionados	Plugin o extension package	Lo instalado, habilitado y cargado coincide con lo revisado.

Un formato no adquiere semántica universal por estar escrito en Markdown, YAML, JSON o TOML. Tampoco debe confundirse el frontmatter de una skill con la metadata de conocimiento del Atlas.

Instrucciones y descubrimiento

openai-codex, claude-code, github-copilot y gemini-cli delimitan los mecanismos por producto. AGENTS.md, CLAUDE.md, .github/copilot-instructions.md y GEMINI.md orientan la consulta, pero no garantizan igual precedencia, alcance o carga.

Un repositorio compartido puede necesitar representaciones compatibles para varios clientes. Antes de duplicar texto, separar reglas comunes y comportamiento del host. Si dos archivos divergen, resolver la decisión en una fuente mantenida y verificar sus representaciones. Un import tampoco debe suponerse soportado por todos los lectores.

Skill: procedimiento con activación delimitada

La especificación de Agent Skills describe un directorio con SKILL.md, frontmatter y cuerpo Markdown. Requiere name y description; el nombre debe coincidir con el directorio y cumplir sus restricciones. Dentro de un directorio llamado review-small-change:

---
name: review-small-change
description: Revisa un diff pequeño y sus pruebas cuando se solicita una revisión de código.
---
 
Lee el diff y los archivos necesarios para evaluar el comportamiento.
Relaciona cada hallazgo con una ubicación y evidencia observable.
Informa incertidumbres y comprobaciones no ejecutadas.

La guía de skills de Codex documenta descubrimiento desde .agents/skills del repositorio y carga progresiva de metadata e instrucciones. La ubicación pertenece al host; el fragmento describe el contenido. Otro runtime puede descubrirlo mediante una ruta o política diferente.

El ejemplo comunica un procedimiento; no concede herramientas, acceso ni autoridad para modificar el repositorio. Si necesita recursos adicionales, comprobar su distribución y disponibilidad. Incluir un script tampoco demuestra que se haya ejecutado.

Hook: observar un evento

La referencia de hooks de Claude Code describe eventos, matchers y handlers. Este fragmento ilustra un handler posterior a herramientas de edición, en una ubicación de configuración admitida:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "node --version" }
        ]
      }
    ]
  }
}

El comando solo informa la versión de Node: no valida el cambio ni impide una escritura. Requiere Node instalado y accesible. Permite observar activación en un laboratorio sin fingir que aplica una política de calidad.

Para un control real, diseñar evento, entrada, resultado y respuesta del host ante rechazo o fallo. Un hook posterior no protege por sí solo una operación ya ocurrida. Consultar la semántica de sus exit codes y decisiones en la versión utilizada; no trasladarla automáticamente a otro producto.

Perfil: rol y herramientas

La configuración de custom agents de Copilot utiliza perfiles con frontmatter y Markdown. Documenta aliases como read y search. Un ejemplo acotado es:

---
name: change-reader
description: Examina cambios y devuelve hallazgos verificables para revisión humana.
tools: ["read", "search"]
---
 
Examina los archivos relevantes y el diff proporcionado.
Distingue defectos observados, hipótesis y evidencia faltante.
Devuelve ubicaciones y una explicación del efecto de cada hallazgo.

Verificar ubicación y opciones para el cliente elegido. El perfil solicita herramientas de lectura y búsqueda; no demuestra aislamiento técnico ni que se haya invocado al especialista. Delegar es una acción adicional.

Como diferencia de formato, la guía de subagents de Codex describe TOML en .codex/agents/, con name, description y developer_instructions. Copiar el YAML anterior a esa ubicación no crea un perfil equivalente. Tampoco deben trasladarse opciones de sesión suponiendo que cambiarán el sandbox o proveedor.

Paquete: metadata y componentes

Claude Code documenta un manifiesto opcional en .claude-plugin/plugin.json. Un ejemplo de metadata es:

{
  "name": "review-lab",
  "version": "0.1.0"
}

La referencia del manifiesto ubica los demás componentes bajo la raíz del plugin, por ejemplo skills/, agents/ y hooks/, fuera de .claude-plugin/. El manifiesto mínimo identifica el paquete; sin componentes adicionales no entrega el procedimiento de la skill anterior.

Gemini CLI tiene otro contrato: su referencia de extensiones documenta gemini-extension.json en la raíz y componentes como skills y hooks/hooks.json. Renombrar un manifiesto de Claude no garantiza conservar comportamiento en Gemini CLI.

Verificación y mantenimiento

Separar cuatro evidencias: el archivo se interpreta, se descubre el componente, se activa en la situación esperada y realiza los efectos autorizados. Probar ausencia, error de carga, fallo del handler y actualización. La sintaxis cubre solamente la primera parte.

Revisar procedencia y scripts antes de habilitar paquetes: ai-supply-chain-risk y least-privilege-for-agents siguen siendo pertinentes. Esta selección cubre ejemplos de cuatro productos y un formato abierto de skill, sin certificar portabilidad entre ellos. coding-agent-prompting-and-context-recipes complementa la consulta y ai-technology-catalog organiza el conjunto.