How do I validate my YAML agent configuration?

You can use the provided Zod schema or CLI validation scripts to ensure your YAML follows the required structure, tool naming conventions, and semver standards.

Does this change how the agent actually functions in Claude Code?

No, YAML agents are loaded and executed identically to Markdown agents; only the underlying file format and structural definition change.

Why should I choose YAML over the default Markdown format?

YAML is superior for machine parsing, programmatic generation, and strict schema validation, which helps reduce human errors in complex agent definitions.

Can I use YAML agents alongside Markdown agents?

Yes, Claude Code is fully compatible with both formats, allowing you to mix .agent.yaml and .md files within the same plugin directory seamlessly.

Is there a specific file extension required for YAML agents?

Yes, YAML agents must use the .agent.yaml extension and be placed in the agents/ directory to be correctly recognized by the system.

YAML Agent Format

Name: YAML Agent Format
Author: MadAppGang

byMadAppGang

•

230

•

Developer Tools

Defines Claude Code agent structures using YAML to provide machine-parseable, schema-validated alternatives to standard Markdown definitions.

The YAML Agent Format skill enables developers to define Claude Code agents using a structured YAML schema instead of traditional Markdown and XML tags. This approach offers significant advantages for automation, including easier programmatic generation, strict validation via Zod or JSON Schema, and improved IDE support with autocompletion and linting. By standardizing the agent definition process, it reduces verbosity while maintaining full compatibility with the Claude Code ecosystem, making it an ideal choice for data-heavy agents and complex CI/CD integration pipelines.

Key Features

01Full compatibility with Claude Code's existing agent loading system

02Reduced verbosity for complex agent definitions with many examples and tools

03230 GitHub stars

04Standardized YAML schema for defining agent roles, tools, and workflows

05Seamless conversion patterns between Markdown and YAML agent formats

06Built-in schema validation using Zod to prevent common configuration errors

Use Cases

01Enforcing strict configuration standards in team-based agent development projects

02Converting existing Markdown-based agents to a more machine-readable format for better tooling support

03Programmatically generating large numbers of specialized agents via automation scripts

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add madappgang/claude-code yaml-agent-format

For use in Claude.ai and ChatGPT

Download Skill