Thulr/agent-skill-kit

Agent DX

La experiencia de desarrollo de una superficie donde un agente de IA es el desarrollador — un SDK, herramienta, salida estructurada, envoltorio de errores o telemetría que un agente consume para construir o actuar a través de ella. La procedencia reside 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 libro de hallazgos + estado del flujo de trabajo cuando se rastrea (REVISAR), o un design-doc.md / refactor-runbook.md / explanation.md (DISEÑO).

Principio fundamental

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

Activación

• Invocación simple ("use agent-dx", "revisar nuestra superficie de herramientas MCP", "iniciar"): cargar references/intent-router.csv, mostrar el menú de intenciones, ofrecer el modo. Esperar. Sin inspección de archivos, llamadas de red ni escrituras.
• Invocación concreta con intención y superficie inferible: saltar al paso 3.
• Ámbito ambiguo: hacer una pregunta bloqueante nombrando la intención o superficie candidata; no inspeccionar sistemas privados primero.

Flujo de trabajo

1. Elegir intención. Cargar references/intent-router.csv; coincidir con hacer, revisar o diseñar. Ambiguo → preguntar una vez.
2. Elegir superficie. Cargar references/intents/<intención>.csv; coincidir 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 REVISAR. Ambiguo → preguntar una vez con el menú.
3. Cargar contexto fundamentado. Cargar solo el playbook de la fila elegida más sus core_refs. No cargar 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 (REVISAR / DISEÑAR) según references/calibration.md: por debajo de Crítico, reducir el alcance, colapsar brechas del mismo mecanismo en un hallazgo sistémico y dividir Ahora vs Después (a medida que crece). El nivel alimenta la emisión, nunca la gravedad.
6. Despachar lentes en paralelo (REVISAR por defecto cuando se permite): una superficie por agente para all; de lo contrario, los tres lentes siguientes. Retroceso secuencial si no hay primitiva de delegación.
7. Aplicar el playbook. Usar las heurísticas etiquetadas para la intención. Para REVISAR, puntuar cada superficie 0–10 (references/core/score-rubric.md); sintetizar los hallazgos de los lentes, preservando los desacuerdos como preguntas abiertas. Aplicar gravedad e IDs estables AGENT-DX-<superficie>-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 o más hallazgos, cualquier gravedad 3–4, o una solicitud de guardar/rastrear/cerrar, cargar references/trackable-findings.md. Si la solicitud nombra un libro de hallazgos existente, estado de flujo de trabajo, PR o ID AGENT-DX-*, leer primero el estado guardado; actualizar estados solo después de que cada regla de verificación pase. De lo contrario, escribir el libro en docs/audits/agent-dx-findings-ledger-<YYYY-MM-DD>-<slug-del-ámbito>.md y el estado del flujo de trabajo en docs/audits/agent-dx-workflow-state-<YYYY-MM-DD>-<slug-del-ámbito>.json (recurrir a audit-artifacts/agent-dx-... si docs/audits/ no se puede escribir). Informar ambas rutas; mantener las hojas de ruta, los problemas y las ediciones no relacionadas con el seguimiento como opt-in.

Modos

Borrador Guiado (predeterminado), Piloto Automático, Interrogatorio — ver references/modes.md. Ofrecer en invocación simple; por defecto 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 de skill.json; REVISAR añade gravedad + verificación por hallazgo y el nivel del proyecto. Nombrar las garantías de consumibilidad por agente que deliberadamente NO se están añadiendo (YAGNI), no solo las que se están añadiendo.

Despacho de subagentes

Predeterminado para REVISAR cuando se permite la delegación; saltar trabajo pequeño o vinculado a secretos. Generar tres lentes en paralelo — contrato-y-esquema (esquemas tipificados del código, envoltorio de errores 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 barrera, muros de credenciales, redacción de contenido) — según references/subagent-dispatch.md, luego sintetizar, ordenando por gravedad.

Mapa de referencia

• references/intent-router.csv + references/intents/<intención>.csv — las dos capas de enrutamiento.
• references/playbooks/<superficie>.md — sdk-design, tools-and-mcp, structured-output, errors-and-retry, sdk-telemetry.
• references/subagent-dispatch.md — indicaciones de tres lentes y síntesis.
• references/core/{severity-rubric,score-rubric,personas,glossary}.md — escalas, audiencia, términos.
• references/{calibration,trackable-findings,modes}.md — compartidos (enlaces simbólicos).
• templates/*.md — change-plan, audit-report, design-doc, refactor-runbook, explanation, más los artefactos de seguimiento compartidos.
• evals/, skill.json — compuertas y procedencia.