What is the purpose of this skill?

To guide users through agent.yaml configuration, SOUL.md writing, and directory structure for agents.

Which sections must I fill in agent.yaml?

Required fields include spec_version, name, version, and description; plus optional model, skills/tools, runtime, and agents sections as needed.

How do I add a new skill?

Create skills/ /SKILL.md with front matter and instructions, ensuring the directory name matches the skill reference used by the agent.

create-agent

npx machina-cli add skill open-gitagent/gitagent/create-agent --openclaw

Files (1)

SKILL.md

2.5 KB

Create & Configure Agents

When to Use

When a user wants to customize their agent.yaml, write a good SOUL.md, add skills/tools/knowledge, or set up compliance.

agent.yaml Reference

Required Fields

spec_version: "0.1.0"
name: my-agent          # Unique identifier
version: 1.0.0          # Semantic version
description: What this agent does

Model Configuration

model:
  preferred: claude-sonnet-4-5-20250929
  fallback:
    - claude-haiku-4-5-20251001
  constraints:
    temperature: 0.2     # 0.0 - 1.0
    max_tokens: 4096
    top_p: 0.9

Skills & Tools

skills:
  - code-review          # Must match directory name in skills/
  - security-audit

tools:
  - lint-check           # Must match filename in tools/ (without .yaml)

Runtime

runtime:
  max_turns: 20          # Max conversation turns
  timeout: 120           # Seconds

Sub-Agents

agents:
  reviewer:
    description: Reviews code quality
    delegation:
      mode: auto
      triggers:
        - "review this"

Writing a Good SOUL.md

A SOUL.md should have these sections:

Core Identity — Who is this agent? One clear sentence.
Communication Style — How does it talk? (direct, friendly, formal, etc.)
Values & Principles — What does it prioritize?
Domain Expertise — What does it know?
Collaboration Style — How does it work with the user?

Writing RULES.md

Structure as:

Must Always — Non-negotiable behaviors
Must Never — Hard boundaries
Output Constraints — Formatting rules
Interaction Boundaries — Scope limits

Adding Skills

Create skills/<name>/SKILL.md:

---
name: my-skill
description: What this skill does
license: MIT
allowed-tools: Read Edit Grep
metadata:
  version: "1.0.0"
---

# Instructions
[Detailed instructions for using this skill]

Adding Tools

Create tools/<name>.yaml:

name: my-tool
description: What this tool does
input_schema:
  type: object
  properties:
    query:
      type: string
      description: Search query
  required:
    - query

Adding Knowledge

Create knowledge/index.yaml:

documents:
  - path: reference.md
    always_load: true    # Include in system prompt
  - path: appendix.md
    always_load: false   # Available on demand

Source

git clone https://github.com/open-gitagent/gitagent/blob/main/examples/gitagent-helper/skills/create-agent/SKILL.mdView on GitHub

Overview

Guides users to tailor agent.yaml, craft a solid SOUL.md, and arrange the directory with skills, tools, and knowledge. It explains required fields, model configuration, and how sub-agents, runtime, and knowledge components fit into a maintainable agent skeleton.

How This Skill Works

It presents a practical, step-by-step workflow: start with agent.yaml essentials, then draft a concise SOUL.md, and finally organize the skills/tools/knowledge directories. The skill references the specific blocks and file layouts described in the content, such as Required Fields, Model Configuration, and skills/tools sections.

When to Use It

You want to customize agent.yaml (name, version, description).
You need to draft a strong SOUL.md with Core Identity and Collaboration Style.
You plan to add or organize skills and tools under skills/ and tools/.
You are configuring runtime, sub-agents, or compliance boundaries in agent.yaml.
You want to add knowledge references via knowledge/index.yaml.

Quick Start

Step 1: Create agent.yaml with required fields (spec_version, name, version, description) and add model, runtime, skills/tools, and optional sub-agents.
Step 2: Write a SOUL.md covering Core Identity, Communication Style, Values & Principles, Domain Expertise, and Collaboration Style.
Step 3: Organize the repo into skills/, tools/, and knowledge/ with appropriate SKILL.md, .yaml, and index.yaml files as described.

Best Practices

Validate required agent.yaml fields (spec_version, name, version, description) are present and correctly formatted.
Keep model configuration within recommended ranges (temperature, max_tokens, top_p) and document choices.
Ensure skill and tool names match their directory/file references (e.g., skills/NAME/SKILL.md and tools/NAME.yaml).
Write a clear SOUL.md with Core Identity, Communication Style, Values & Principles, Domain Expertise, and Collaboration Style.
Document knowledge and tooling setup with knowledge/index.yaml and organized folders for easy discovery.

Example Use Cases

An agent named 'my-agent' defined in agent.yaml with semantic version 1.0.0 and a simple model config.
A sub-agent 'reviewer' under agents with a descriptive purpose and a delegation trigger.
A tools entry like lint-check that matches the filename in tools/ (without .yaml).
A knowledge/index.yaml referencing reference.md (always_load) and appendix.md (on-demand).
A SOUL.md that includes Core Identity, Communication Style, and Values & Principles for clear behavior.

Frequently Asked Questions

Add this skill to your agents