---
name: yaml-schema
description: "Loading agent.yml, defining schema models, and validating the specification (definitions, hierarchy, security). Primary task is tasks/0002-yaml-schema-and-validation.md."
generated: true
source: .ai/skills/yaml-schema.md
---

<!--
This file is generated by tools/skills.
Do not edit this file directly.
Edit .ai/skills/yaml-schema.md and run `make generate-ai`.
-->

# Skill: YAML Schema & Validation

## When to use this skill

Use this when working on loading YAML configs, defining schema models, or
validating the Agent Engine specification. Primary task:
`tasks/0002-yaml-schema-and-validation.md`.

## Files to read first

- `AGENTS.md`
- `docs/YAML_SPEC.md`
- `examples/agents.yml`
- `examples/config.schema.json`
- `docs/adr/0002-yaml-is-compiled-not-executed-directly.md`

## Architecture rules

- YAML is declarative data, never code.
- The spec has two halves: flat declarations and `graph` topology.
- Validation must happen before compilation.
- Runtime layers consume only validated/compiled models, never raw YAML dicts.
- Secrets are never values in YAML.

## Implementation rules

- Define typed schema models in `src/agentplatform/spec`.
- Validation belongs in `src/agentplatform/validation`.
- Report all validation errors with useful locations.
- Enforce: required `system` and `graph`; one graph root; graph ids exist in
  `orchestrators` or `agents`; no cycles; referenced resolvers/tools/MCPs exist;
  orchestrators have `prompts.orchestrator`; model overrides are complete;
  protected nodes require the access plugin at startup.
- Keep schema/validation separate from the compiler.

## Validation checklist

- [ ] Schema models cover `docs/YAML_SPEC.md`.
- [ ] `examples/agents.yml` validates successfully.
- [ ] Dangling references, missing/multiple roots, and cycles fail clearly.
- [ ] Unknown keys and hardcoded secrets are rejected.
- [ ] Tests cover valid and invalid specs.
- [ ] `make check` passes.

## Common mistakes to avoid

- Mixing validation with compilation or runtime logic.
- Failing fast on the first error instead of collecting all errors.
- Reintroducing the old `definitions` / `hierarchy` shape.
- Letting unknown/typo'd keys pass silently.