yaml-schema

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

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.