ALDC + Agent Skills + Skills Evidencing
Arquitectura ALDC Core v1.1 presentada en 5 capas. Las ~44 piezas componibles agrupadas en 4 familias. Instalación en vivo desde VS Code Marketplace. Skills Evidencing — el patrón que hace auditable al agente. Demo de skill-diagnostics.
Instalación ALDC en vivo
El bloque arranca aterrizando ALDC. La extensión se instala desde el Marketplace y el árbol de .github/ se puebla en vivo. A partir de aquí, todo lo que se discute tiene un referente real en pantalla.
Punto de partida: el repo-starter tiene el .github/ limpio — solo copilot-instructions.md (contrato del workshop) y skills/skill-diagnostics/SKILL.md (la skill específica del workshop).
.github/
├── copilot-instructions.md ← contrato del workshop
└── skills/
└── skill-diagnostics/
└── SKILL.md ← la skill específica del workshop
Los 3 pasos de la instalación
Instalar la extensión desde Marketplace
Ctrl+Shift+X → buscar "AL Development Collection" → publisher JavierArmestoGonzalez → Install
Copiar ALDC al workspace
Ctrl+Shift+P → "AL Collection: Install Toolkit to Workspace" → Enter. Este segundo paso es clave: lo que queda en el repo es versionable, no depende de que la extensión esté instalada en cada máquina.
Refrescar explorador
Ver .github/ poblarse con agents/, instructions/, prompts/, skills/, workflows/. El contrato del workshop y la skill original se mantienen intactos.
ALDC añade, no sobrescribe. El contrato del workshop se mantiene, la skill propia se mantiene. Ecosistema abierto, no plataforma cerrada.
Arquitectura ALDC · 5 capas
Capa humana
decisions.md · memory.md · approvals. El humano firma, el agente ejecuta.
Capa de orquestación
al-conductor como thin-router. No genera código, coordina subagentes.
Capa de roles
al-architect · al-spec.create (workflow) · al-planning · al-implement · al-review (subagents)
Capa de skills
15 skills on-demand cargadas por los agentes. No son código — son contratos con frontmatter + patrones + constraints.
Capa de contrato
copilot-instructions.md · app.json · 7 instructions auto-aplicadas por tipo de fichero
Los 3 pilares no negociables
Spec-driven
Nada se implementa sin spec aprobada.
HITL gates
Plan approval, phase commit, PR. Humano entre fases.
Skills Evidencing
Cada agente declara qué skill cargó y qué patrón aplicó.
Las 4 familias · ~44 piezas reales
Números reales del repo · ALDC Core v1.1
| Tipo | Cantidad | Qué son |
|---|---|---|
| Agentes públicos | 4 | al-architect, al-conductor, al-developer, al-presales |
| Subagentes | 3 | al-planning, al-implement, al-review (invocados por el conductor) |
| Skills | 15 | 11 core + 3 pack BC Agents + 1 integración (extension-manifest) |
| Workflows | 10 | 6 públicos + 4 del pack BC Agents |
| Instructions | 7 | Auto-aplicadas según el tipo de fichero |
| Extra | 1 | al-agent-builder (del pack BC Agents) |
| TOTAL | ~44 | piezas componibles |
Agrupadas por momento del ciclo
Anatomía de una skill
Todas las skills ALDC comparten la misma estructura canónica. Una vez que se entiende esta anatomía, leer cualquier nueva skill toma 30 segundos.
- Frontmatter
name+description— Copilot auto-carga según la description, no con@file - Sección
## Core Patterns— los patrones concretos aplicables (API page v2.0, event subscribers, permission design, etc.) - Sección
## Constraints— es contrato, no decorado - Referencias cruzadas — no se duplica contenido
Una skill ALDC no es un prompt bonito. Es un contrato con frontmatter, patterns, workflow, constraints y referencias cruzadas. Si falta alguna parte, no es una skill — es un truco.
Skills Evidencing · "¿de dónde sacó el agente esta decisión?"
Todo equipo que ha metido LLMs en producción se ha hecho esta pregunta. Y la respuesta "porque sí" bloquea adopción en cualquier contexto regulado — auditoría, AppSource, contratos enterprise.
Skills Evidencing es el mecanismo para que la pregunta tenga respuesta.
Los 5 formatos de evidencia
| Agente / rol | Dónde emite evidencia | Formato |
|---|---|---|
| al-architect | Top del architecture.md | > **Skills applied**: skill-api, skill-events |
| al-developer | Inicio de cada respuesta | > **Skills loaded**: skill-debug (root cause analysis) |
| al-implement-subagent | Phase Summary al conductor | Sección ### Skills Loaded |
| al-review-subagent | Review del código | Tabla Skills Compliance Check |
| al-conductor | phase-complete.md, plan-complete.md | Tabla Skills Applied + Utilization Summary |
La evidencia viaja de abajo arriba. El subagente declara qué cargó, el review valida que se aplicó, el conductor consolida en el phase-complete. Cuando alguien abre el PR, tiene la cadena completa.
Skills Evidencing no sustituye la revisión humana — la facilita. El humano sigue decidiendo, pero ahora decide con información. Si el subagente dice que cargó skill-performance pero el código no tiene SetLoadFields, el review-subagent lo flaggea como Major. El sistema se audita a sí mismo.
skill-diagnostics · auditoría estática contra el contrato
skill-diagnostics es la skill específica del workshop, creada para estrenarse hoy e incorporarse al catálogo ALDC. Complementa a skill-performance: donde performance hace triage de runtime, diagnostics hace auditoría estática contra el contrato del proyecto.
Anatomía de skill-diagnostics
- Frontmatter ·
name+description. Copilot auto-carga con queries tipo "audit workspace", "compliance check" - Purpose · reporta, nunca arregla
- When to Load · 5 casos de uso documentados
- Pattern 1 · Las 4 clases de findings · Compliance / Code quality / Test coverage / Permissions
- Pattern 2 · Severidades · Blocker / Major / Minor / Nit, regla "si dudas, baja"
- Pattern 3 · Output format · la forma exacta del reporte
- Constraints · NEVER modifies code. NEVER invents rules.
NEVER modifies code. NEVER invents rules. Esto es lo que separa una skill de producción de un prompt ingenioso.
Invocación en Copilot Chat
Load skill-diagnostics and scan the workspace. Follow the output format strictly and include the Skills Applied block at the end.
Copilot encuentra la skill por su description del frontmatter. En ALDC Core v1.1 esto reemplazó a las referencias @file — es más natural y el catálogo se auto-publica al ecosistema de Copilot Chat.
Hallazgos esperados en el reporte
El output defectuoso del Bloque 1 (o el fallback pre-cargado) contiene estos defectos intencionados, cada uno asociado a una clase y severidad:
DataClassification a nivel objeto
Compliance
Blocker
ToolTip
Compliance
Major
app.json
Compliance
Major
Lo importante no es la lista de hallazgos. Es que cada hallazgo está vinculado a una regla concreta del copilot-instructions.md o a una declaración de app.json. El reporte es auditable porque la skill evidencia su lógica. Y no inventa reglas — si se quita el copilot-instructions.md, la skill avisa de que escaneará con muchas menos reglas.
Inspeccionad una skill real de ALDC en vuestra máquina
Tras la instalación, tenéis .github/skills/ con 15 skills reales en vuestro workspace. El ejercicio es abrir una y reconocer las piezas canónicas.
- Abrid
.github/skills/skill-api/SKILL.mdo la que más os llame la atención - Identificad las 4 piezas canónicas: frontmatter / Core Patterns / Constraints / referencias cruzadas
- Preguntaros: ¿qué habría que añadir al
copilot-instructions.mddel workshop para que esta skill cargue automáticamente en el contexto de un prompt?
Qué cubre este bloque
Instalación en vivo
De 2 ficheros iniciales a ~44 piezas reales tras instalar ALDC desde Marketplace.
Arquitectura en 5 capas
Contrato · skills · roles · orquestación · humana. Los 3 pilares no negociables.
Las 4 familias
Diagnóstico · generación · orquestación · evidencia. Anatomía de una skill canónica.
Skills Evidencing
Los 5 formatos de evidencia que recorren el pipeline. Por qué hace auditable al agente.
Demo skill-diagnostics
Reporta · nunca arregla · nunca inventa reglas. Las 4 clases de findings.