Skip to content

abbyfile-format.md

Latest commit

 

History

History
177 lines (135 loc) · 5.46 KB

abbyfile-format.md

File metadata and controls

177 lines (135 loc) · 5.46 KB
title Abbyfile Format
parent Guides
nav_order 1

Abbyfile Format Guide

This guide explains the two files that define agents: the Abbyfile manifest and agent .md files.

Abbyfile (YAML Manifest)

The manifest lives at your project root and declares which agents to build. The CLI accepts both Abbyfile and abbyfile.yaml as filenames — when no -f flag is given, it checks for Abbyfile first, then abbyfile.yaml.

version: "1"
agents:
  go-pro:
    path: .claude/agents/go-pro.md
    version: 0.1.0
  tool-eng:
    path: .claude/agents/tool-eng.md
    version: 0.2.0

Fields

Field Required Description
version yes Manifest format version (currently "1")
agents yes Map of agent name → agent reference
agents.<name>.path yes Path to the agent's .md file (relative to Abbyfile)
agents.<name>.version yes Semantic version for the built binary

The agent name (the YAML key, e.g. go-pro) becomes the binary name. The version here overrides anything in the .md file.

Agent .md Files (Dual Frontmatter)

Each agent .md file has two YAML frontmatter blocks followed by the system prompt body:

---
name: go-pro
description: "when editing Go code files"
memory: project
---

---
description: "A Go development assistant for idiomatic, concurrent systems"
tools: Read, Write, Edit, Bash, Glob, Grep
---

You are a senior Go developer with deep expertise...

Block 1 — Agent Identity

The first frontmatter block identifies the agent to Claude Code:

Field Required Description
name yes Agent name (used as binary name if not overridden by Abbyfile)
description no Short description shown in Claude Code's agent picker
memory no Set to any value (e.g. project) to enable persistent memory
model no Model hint for the runtime (surfaced in --describe and MCP instructions). Can be overridden at install time (--model) or via config set model

Block 2 — Tools and Detailed Description

The second frontmatter block declares tools and a fuller description:

Field Required Description
description no Detailed description (overrides block 1 if present)
tools no Comma-separated list of builtin tool names
custom_tools no List of custom CLI tool definitions (see Tools guide)
skills no List of skill definitions for plugin output (see Plugins guide)
model no Hint for Claude Code

Skills

Skills are markdown files that get packaged into a Claude Code plugin directory when building with --plugin. Each skill becomes a skills/<name>/SKILL.md in the plugin.

skills:
  - name: review-pr
    description: "Review a pull request for quality"
    path: skills/review-pr.md
  - name: write-tests
    description: "Generate unit tests"
    path: skills/write-tests.md
Field Required Description
name yes Skill name (used as directory name)
description yes Short description for Claude Code
path yes Path to skill markdown file (relative to agent .md file)

Prompt Body

Everything after the second --- delimiter is the system prompt. This gets embedded into the compiled binary and is returned by --custom-instructions and exposed via MCP.

Available Tools

Agents declare tools by their Claude Code name. The builder maps these to MCP tool implementations:

Declare in .md MCP tool name Description
Read read_file Read file contents at an absolute path
Write write_file Write content to a file, creating parent dirs
Edit edit_file Find-and-replace a unique string in a file
Bash run_command Execute a shell command with timeout
Glob glob_files Find files matching a glob pattern (supports **)
Grep grep_search Search file contents with regex

Example:

tools: Read, Write, Bash

If memory is enabled, memory tools (memory_read, memory_write, memory_list, memory_delete) are added automatically.

Minimal Example

The smallest valid setup:

Abbyfile:

version: "1"
agents:
  helper:
    path: agents/helper.md
    version: 0.1.0

agents/helper.md:

---
name: helper
---

---
tools: Read
---

You are a helpful assistant.

Build and run:

make build && ./build/abby build
./build/helper --version        # helper v0.1.0
./build/helper validate         # check wiring

File Organization

A typical project layout:

Abbyfile                        # manifest (or abbyfile.yaml)
.claude/agents/
  go-pro.md                      # agent definition + prompt
  tool-eng.md                    # another agent
  skills/                        # skill markdown files (for --plugin)
    review-pr.md
    write-tests.md
build/
  abby                           # CLI tool (from make build)
  go-pro                         # compiled agent (from abby build)
  tool-eng                       # compiled agent
  go-pro.claude-plugin/          # plugin directory (from abby build --plugin)
.mcp.json                        # auto-generated by abby build

The .claude/agents/ path is a convention — you can put .md files anywhere and point to them from the Abbyfile. Skill paths are relative to the agent .md file.