agentconfig.ing
AGENTYAML(5)AGENTYAML(5)

NAME

agent.yaml — instruction file for

SYNOPSIS

./

METADATA

FORMATYaml
FILENAMEagent.yaml
CASE SENSITIVEYes
TOOL
ENCODINGUTF-8
GIT COMMITTEDYes
SINCEGitAgent v0.1.0 (2025)

DESCRIPTION

agent.yaml is the manifest file for the GitAgent specification, which defines AI agents as portable Git repository structures. Instead of encoding agent behavior in platform-specific formats, GitAgent uses a collection of Markdown files (SOUL.md for identity, RULES.md for constraints, DUTIES.md for objectives) organized under a single YAML manifest.

The specification is framework-agnostic — the same agent repo can be consumed by Claude Code, OpenAI, CrewAI, LangChain, or any runtime that implements a GitAgent adapter. This portability is the key differentiator: agents become versionable, forkable, and composable using standard Git workflows.

The skills directory contains SKILL.md files that define discrete, reusable capabilities. Each skill has defined inputs, outputs, and step-by-step instructions. Skills can be shared across agents, creating an ecosystem of composable agent behaviors.

The tools directory defines external integrations (APIs, MCP servers, CLI tools) that the agent can invoke. The workflows directory enables multi-step orchestration sequences that compose skills and tools into end-to-end processes.

GitAgent draws inspiration from Infrastructure-as-Code practices: agents are declared, versioned, reviewed via PR, and deployed from repositories. This makes agent development accessible to teams already familiar with Git-based workflows.

STRUCTURE

├──Overview / MetadataREQUIRED
Top-level fields: name, version, description, author, license. Identifies the agent and provides discoverability metadata.
├──Structure (agent.yaml fields)REQUIRED
Declares the repo layout: paths to SOUL.md, RULES.md, DUTIES.md, and the skills/, tools/, and workflows/ directories. The manifest is the single entry point for agent resolution.
├──SOUL.mdREQUIRED
The agent's identity and personality. Defines persona, tone, values, and behavioral principles. Equivalent to a system prompt but versioned and portable.
├──RULES.mdREQUIRED
Hard constraints and guardrails. Defines what the agent must never do, safety boundaries, output format requirements, and compliance rules.
├──DUTIES.md
The agent's responsibilities and objectives. Lists the tasks the agent is expected to perform, success criteria, and escalation policies.
├──Skills Directory
A directory of SKILL.md files, each defining a discrete capability with inputs, outputs, and execution steps. Skills are composable and reusable across agents.
└──Tools Directory
External tool integrations the agent can invoke. Each tool definition includes the interface contract (MCP, REST, CLI) and authentication requirements.

ANNOTATED EXAMPLE

agent.yaml
yaml
1# GitAgent manifest — defines a portable AI agent as a repo structure
2name: code-review-agent
3version: 1.2.0
4description: Automated code review agent with security focus
5author: acme-team
6license: MIT
7
8# Identity and behavioral core
9soul: SOUL.md          # Persona, tone, values
10rules: RULES.md        # Hard constraints, safety guardrails
11duties: DUTIES.md      # Responsibilities, success criteria
12
13# Composable capabilities
14skills:
15  path: skills/        # Each .md file = one discrete skill
16  # skills/review-pr.md
17  # skills/check-security.md
18  # skills/suggest-tests.md
19
20# External tool integrations
21tools:
22  path: tools/         # Tool interface definitions
23  # tools/github-api.md
24  # tools/sonarqube.md
25
26# Multi-step workflows
27workflows:
28  path: workflows/     # Orchestration sequences
29  # workflows/full-review.md
30
31# Runtime hints (optional, adapter-specific)
32runtime:
33  context_window: 128000
34  temperature: 0.3
35  max_tokens: 4096

COMMON MISTAKES

Gotchas
✗WRONG Putting personality traits in RULES.md
✓RIGHT Personality goes in SOUL.md; RULES.md is for hard constraints only

GitAgent separates identity (SOUL.md) from constraints (RULES.md) deliberately. Mixing them causes confusion when different runtimes interpret the files — constraints should be enforceable, while personality is aspirational.

✗WRONG Defining agent logic directly in agent.yaml
✓RIGHT agent.yaml is a manifest — it points to files, it doesn't contain logic

The agent.yaml file is a declarative manifest that maps the repo structure. All behavioral content lives in the referenced Markdown files (SOUL.md, RULES.md, DUTIES.md) and skill/tool directories. Keep the YAML purely structural.

✗WRONG Assuming a specific LLM runtime or provider in skill definitions
✓RIGHT Write skills as provider-agnostic instructions

GitAgent is framework-agnostic by design. Skills should describe what to do, not how a specific model should do it. Avoid Claude-specific or OpenAI-specific syntax in skill files — the runtime adapter handles translation.

✗WRONG Omitting version field in agent.yaml
✓RIGHT Always include a semver version for reproducibility

Without a version, consumers of your agent cannot pin to a known-good state. GitAgent repos are meant to be shared and composed — versioning enables dependency management and rollback.

USED BY

SIMILAR FILES

SOUL.md— Agent Soul Definition
SKILL.md— Agent Skill Definition
agentconfig.ing2026-03-17AGENTYAML(5)