ALDC + Agent Skills + Skills Evidencing
ALDC Core v1.1 architecture presented in 5 layers. The ~44 composable pieces grouped into 4 families. Live installation from VS Code Marketplace. Skills Evidencing — the pattern that makes the agent auditable. skill-diagnostics demo.
Live ALDC installation
The block opens by grounding ALDC. The extension is installed from the Marketplace and the .github/ tree is populated live. From this point, everything discussed has a real reference on screen.
Starting point: the repo-starter has a clean .github/ — only copilot-instructions.md (workshop contract) and skills/skill-diagnostics/SKILL.md (the workshop-specific skill).
.github/
├── copilot-instructions.md ← workshop contract
└── skills/
└── skill-diagnostics/
└── SKILL.md ← workshop-specific skill
The 3 installation steps
Install the extension from Marketplace
Ctrl+Shift+X → search "AL Development Collection" → publisher JavierArmestoGonzalez → Install
Copy ALDC to the workspace
Ctrl+Shift+P → "AL Collection: Install Toolkit to Workspace" → Enter. This second step is key: what ends up in the repo is versionable, it doesn't depend on the extension being installed on every machine.
Refresh the explorer
Watch .github/ populate with agents/, instructions/, prompts/, skills/, workflows/. The workshop contract and original skill remain intact.
ALDC adds, it doesn't overwrite. The workshop contract is preserved, the custom skill is preserved. Open ecosystem, not a closed platform.
ALDC Architecture · 5 layers
Human layer
decisions.md · memory.md · approvals. The human signs, the agent executes.
Orchestration layer
al-conductor as thin-router. Doesn't generate code, coordinates subagents.
Roles layer
al-architect · al-spec.create (workflow) · al-planning · al-implement · al-review (subagents)
Skills layer
15 on-demand skills loaded by agents. Not code — they are contracts with frontmatter + patterns + constraints.
Contract layer
copilot-instructions.md · app.json · 7 instructions auto-applied by file type
The 3 non-negotiable pillars
Spec-driven
Nothing is implemented without an approved spec.
HITL gates
Plan approval, phase commit, PR. Human between phases.
Skills Evidencing
Each agent declares which skill it loaded and which pattern it applied.
The 4 families · ~44 real pieces
Real numbers from the repo · ALDC Core v1.1
| Type | Quantity | What they are |
|---|---|---|
| Public agents | 4 | al-architect, al-conductor, al-developer, al-presales |
| Subagents | 3 | al-planning, al-implement, al-review (invoked by the conductor) |
| Skills | 15 | 11 core + 3 BC Agents pack + 1 integration (extension-manifest) |
| Workflows | 10 | 6 public + 4 from BC Agents pack |
| Instructions | 7 | Auto-applied according to file type |
| Extra | 1 | al-agent-builder (from BC Agents pack) |
| TOTAL | ~44 | composable pieces |
Grouped by cycle stage
Anatomy of a skill
All ALDC skills share the same canonical structure. Once you understand this anatomy, reading any new skill takes 30 seconds.
- Frontmatter
name+description— Copilot auto-loads based on description, not with@file ## Core Patternssection — the concrete applicable patterns (API page v2.0, event subscribers, permission design, etc.)## Constraintssection — it's a contract, not decoration- Cross-references — content is never duplicated
An ALDC skill is not a pretty prompt. It's a contract with frontmatter, patterns, workflow, constraints and cross-references. If any part is missing, it's not a skill — it's a trick.
Skills Evidencing · "where did the agent get this decision from?"
Every team that has put LLMs into production has asked this question. And the answer "just because" blocks adoption in any regulated context — audits, AppSource, enterprise contracts.
Skills Evidencing is the mechanism so the question has an answer.
The 5 evidence formats
| Agent / role | Where it emits evidence | Format |
|---|---|---|
| al-architect | Top of architecture.md | > **Skills applied**: skill-api, skill-events |
| al-developer | Start of each response | > **Skills loaded**: skill-debug (root cause analysis) |
| al-implement-subagent | Phase Summary to conductor | ### Skills Loaded section |
| al-review-subagent | Code review | Skills Compliance Check table |
| al-conductor | phase-complete.md, plan-complete.md | Skills Applied table + Utilization Summary |
Evidence travels bottom-up. The subagent declares what it loaded, the review validates it was applied, the conductor consolidates in the phase-complete. When someone opens the PR, they have the full chain.
Skills Evidencing doesn't replace human review — it facilitates it. The human still decides, but now decides with information. If the subagent says it loaded skill-performance but the code has no SetLoadFields, the review-subagent flags it as Major. The system audits itself.
skill-diagnostics · static audit against the contract
skill-diagnostics is the workshop-specific skill, created to debut today and be incorporated into the ALDC catalog. It complements skill-performance: where performance does runtime triage, diagnostics does static auditing against the project contract.
Anatomy of skill-diagnostics
- Frontmatter ·
name+description. Copilot auto-loads with queries like "audit workspace", "compliance check" - Purpose · reports, never fixes
- When to Load · 5 documented use cases
- Pattern 1 · The 4 finding classes · Compliance / Code quality / Test coverage / Permissions
- Pattern 2 · Severities · Blocker / Major / Minor / Nit, rule "when in doubt, go lower"
- Pattern 3 · Output format · the exact shape of the report
- Constraints · NEVER modifies code. NEVER invents rules.
NEVER modifies code. NEVER invents rules. This is what separates a production skill from a clever prompt.
Invocation in Copilot Chat
Load skill-diagnostics and scan the workspace. Follow the output format strictly and include the Skills Applied block at the end.
Copilot finds the skill by its frontmatter description. In ALDC Core v1.1 this replaced @file references — it's more natural and the catalog self-publishes to the Copilot Chat ecosystem.
Expected findings in the report
The defective output from Block 1 (or the pre-loaded fallback) contains these intentional defects, each associated with a class and severity:
DataClassification at object level
Compliance
Blocker
ToolTip
Compliance
Major
app.json
Compliance
Major
What matters is not the list of findings. It's that each finding is linked to a specific rule from copilot-instructions.md or a declaration in app.json. The report is auditable because the skill evidences its logic. And it doesn't invent rules — if copilot-instructions.md is removed, the skill warns that it will scan with far fewer rules.
Inspect a real ALDC skill on your machine
After installation, you have .github/skills/ with 15 real skills in your workspace. The exercise is to open one and recognize the canonical pieces.
- Open
.github/skills/skill-api/SKILL.mdor whichever catches your attention - Identify the 4 canonical pieces: frontmatter / Core Patterns / Constraints / cross-references
- Ask yourself: what would need to be added to the workshop's
copilot-instructions.mdfor this skill to load automatically in a prompt's context?
What this block covers
Live installation
From 2 initial files to ~44 real pieces after installing ALDC from Marketplace.
5-layer architecture
Contract · skills · roles · orchestration · human. The 3 non-negotiable pillars.
The 4 families
Diagnostics · generation · orchestration · evidence. Anatomy of a canonical skill.
Skills Evidencing
The 5 evidence formats that run through the pipeline. Why it makes the agent auditable.
skill-diagnostics demo
Reports · never fixes · never invents rules. The 4 finding classes.