Communitygithub.com

ké de experiencia de agente (Agent DX)

Un kit de habilidades para agentes que el mantenedor realmente usa — instálalo mediante npx skills add justinramos101/agent-skill-kit

¿Qué es ké de experiencia de agente (Agent DX)?

Agent DX es un marco de trabajo integral para auditar y diseñar la experiencia de desarrollo orientada a agentes de IA. Su objetivo principal es garantizar que cualquier SDK, herramienta, esquema de salida estructurada, envoltura de errores o superficie de telemetría sea consumible de forma autónoma por un agente, sin depender de tooltips ni intervención humana. Se centra en contratos tipados, recuperación ante fallos diseñada explícitamente, límites de confianza cerrados por defecto y una calibración según la escala del proyecto. Soporta los modos de invocación guiada, piloto automático y «gríllame», y produce artefactos como planes de cambio, informes de auditoría con hallazgos rastreables, documentos de diseño, runbooks de refactorización o explicaciones de principios. Su flujo de trabajo enruta la intención (hacer, revisar, diseñar), selecciona la superficie (diseño de SDK, herramientas/MCP, salida estructurada, errores/reintentos, telemetría), carga el contexto adecuado (playbooks, referencias) y despacha en paralelo tres lentes de revisión: contrato/esquema, recuperación del agente y confianza/aislamiento. Genera un ledger de hallazgos y un estado de flujo de trabajo persistente cuando se requiere seguimiento. Es especialmente útil para equipos que construyen herramientas para asistentes de código como Claude Code, Cursor o Codex, ya que eleva el estándar de lo que significa que una superficie sea «consumible por un agente», y detecta problemas que el testing tradicional no cubre.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add justinramos101/agent-skill-kit

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Agent DX (Experiencia de Agente)

La experiencia de desarrollo de una superficie donde un agente de IA es el desarrollador — un SDK, herramienta, salida estructurada, envoltura de errores o telemetría que un agente consume para construir con ella o actuar a través de ella. La procedencia vive en skill.json; este archivo es solo enrutamiento en tiempo de ejecución.

Produce: un change-plan.md (HACER), un audit-report.md más un ledger de hallazgos + estado del flujo de trabajo cuando se rastrea (REVISAR), o un design-doc.md / refactor-runbook.md / explanation.md (DISEÑAR).

Principio central

Un agente consume la superficie solo, a velocidad de máquina, sin ningún tooltip al que recurrir. Por lo tanto, la barra para cualquier SDK, herramienta, error o span es si un consumidor estocástico puede analizarlo, recuperarse de él y no ser dañado por él: contratos tipados sobre prosa; recuperación diseñada, no esperada; el límite de confianza cerrado por defecto. Se sitúa sobre el piso de cliente HTTP que poseen dx-audit / dx-design, sin reemplazarlo nunca.

Activación

  • Invocación simple ("use agent-dx", "start"): muestra un menú compacto: elección de modo (guiado / piloto automático / ¿gríllame?) e intenciones numeradas desde el enrutador. Espera. Sin inspección de archivos, sin llamadas de red, sin escrituras.
  • Invocación concreta con intención y superficie inferible: salta al paso 3.
  • Invocación ambigua: pregunta una vez — p. ej., "¿Estás auditando un SDK, un esquema de herramienta, una envoltura de salida estructurada o una superficie de telemetría?" o "¿Es esto una revisión de contrato/recuperación o una auditoría de límite de confianza?"

Flujo de trabajo

  1. Elegir intención. Carga references/intent-router.csv; coincide con do, review o design. Ambiguo → pregunta una vez.
  2. Elegir superficie. Carga references/intents/<intent>.csv; coincide con una o más de sdk-design, tools-and-mcp, structured-output, errors-and-retry, sdk-telemetry — o all para un despliegue en abanico de REVISIÓN. Ambiguo → pregunta una vez con el menú.
  3. Cargar contexto fundamentado. Carga solo el playbook de la fila elegida más sus core_refs. No cargues otros playbooks (la fila review/all no lleva ninguno — cada agente de superficie carga el suyo; ver paso 6).
  4. Identificar la persona objetivo desde references/core/personas.md.
  5. Luego calibrar según la escala del proyecto (REVISIÓN / DISEÑO) según references/calibration.md: por debajo de Carga-Estructural, acota el alcance, colapsa brechas del mismo mecanismo en un único hallazgo sistémico y divide Ahora vs Después (a medida que crece). El nivel alimenta la emisión, nunca la severidad.
  6. Despachar lentes en paralelo (REVISIÓN por defecto cuando está permitido): una superficie por agente para all; en caso contrario, las tres lentes siguientes. Retroceso secuencial si no hay primitiva de delegación.
  7. Aplicar el playbook. Usa las heurísticas etiquetadas para la intención. Para REVISIÓN, puntúa cada superficie de 0 a 10 (references/core/score-rubric.md); sintetiza los hallazgos de las lentes, preservando desacuerdos como preguntas abiertas. Aplica severidad e IDs estables AGENT-DX-<surface>-NNN (references/core/severity-rubric.md): AGENT-DX-SDK, AGENT-DX-TOOL, AGENT-DX-OUT, AGENT-DX-ERR, AGENT-DX-TEL.
  8. Emitir. HACER → templates/change-plan.md. REVISAR → templates/audit-report.md. DISEÑAR → templates/design-doc.md (forma), templates/refactor-runbook.md (secuencia de endurecimiento) o templates/explanation.md (explicar un principio).
  9. Crear, reanudar o cerrar estado de seguimiento (REVISAR). Para una auditoría con 7+ hallazgos, cualquier severidad 3–4, o una solicitud de guardar/rastrear/cerrar, carga references/trackable-findings.md. Si la solicitud nombra un ledger existente, estado del flujo de trabajo, PR o ID AGENT-DX-*, lee el estado guardado primero; actualiza los estados solo después de que cada regla de verificación pase. De lo contrario, escribe el ledger en docs/audits/agent-dx-findings-ledger-<YYYY-MM-DD>-<scope-slug>.md y el estado del flujo de trabajo en docs/audits/agent-dx-workflow-state-<YYYY-MM-DD>-<scope-slug>.json (opta por audit-artifacts/agent-dx-... si docs/audits/ no se puede escribir). Reporta ambas rutas; mantén hojas de ruta, incidencias y ediciones no relacionadas con el seguimiento como opt-in.

¿Dirección incorrecta? Si el usuario dice que esto no es lo que quería, vuelve al paso 1 (Elegir intención) — no parchees en la dirección incorrecta. Replantea la comprensión corregida y vuelve a planificar.

Modos

Borrador Guiado (por defecto), Piloto Automático, Gríllame — consulta references/modes.md. Ofrece en invocación simple; por defecto a Borrador Guiado en invocaciones concretas.

Requisitos de salida

Cada salida nombra la intención, superficie(s), persona, playbook(s) aplicados y fuentes de fundamentación desde skill.json; REVISAR añade severidad + verificación por hallazgo y el nivel del proyecto. Nombra las garantías de consumibilidad por agente que deliberadamente NO estás añadiendo (YAGNI), no solo las que estás añadiendo.

Despacho de subagentes

Por defecto para REVISAR cuando la delegación está permitida; saltar trabajos pequeños o con secretos. Genera tres lentes en paralelo — contrato-y-esquema (esquemas tipados desde código, envoltura de error estable, salida validada), recuperación-del-agente (detener+verificar, errores con forma de reintento, reintento semántico, bucle acotado), confianza-y-aislamiento (inyección de metadatos de herramienta, puntos de control de guardarraíles, muros de credenciales, redacción de contenido) — según references/subagent-dispatch.md, luego sintetiza, ordenando por severidad.

Mapa de referencias

  • references/intent-router.csv + references/intents/<intent>.csv — las dos capas de enrutamiento.
  • references/playbooks/<surface>.md — sdk-design, tools-and-mcp, structured-output, errors-and-retry, sdk-telemetry.
  • references/subagent-dispatch.md — prompts de las tres lentes y síntesis.
  • references/core/*.md — severidad, puntuación, personas, glosario.
  • references/{calibration,trackable-findings,modes}.md — compartidos (enlaces simbólicos).
  • templates/*.md — change-plan, audit-report, design-doc, refactor-runbook, explanation, además de los artefactos compartidos de seguimiento.
  • evals/, skill.json — compuertas y procedencia.

Skills relacionados