Internal Structure and File Format for Creating a Custom Agent in Agency-Agents

Agency-Agents defines custom agents as self-contained Markdown files with YAML frontmatter and standardized H2 sections that are parsed by scripts/convert.sh to generate tool-specific integrations for Claude Code, Cursor, and OpenCode.

The msitarzewski/agency-agents repository treats agent definitions as the single source of truth for AI behavior, storing each personality, workflow, and deliverable specification in structured Markdown documents. Understanding the internal structure and file format for creating a custom agent allows you to extend the ecosystem with specialized roles that integrate seamlessly across multiple development tools.

The Markdown-First Architecture

Each agent in Agency-Agents is a plain-text Markdown file (.md) that serves as both documentation and executable specification. The repository organizes these files into category folders such as specialized/, engineering/, and design/ to maintain logical separation of concerns.

The conversion pipeline located at scripts/convert.sh recursively scans these directories, parsing each Markdown file to extract frontmatter metadata and section content. It then generates tool-specific configuration files—such as .cursor/rules/ for Cursor, ~/.claude/agents/ for Claude Code, and ~/.config/opencode/agent/ for OpenCode—ensuring the agent behaves consistently across different AI coding environments.

Required File Format Components

YAML Frontmatter

Every agent file must begin with YAML frontmatter enclosed by triple dashes (---). This metadata block defines the agent’s identity for the conversion pipeline.

---
name: Frontend Developer
description: Expert frontend developer specializing in React and TypeScript
color: cyan
---

The name field becomes the agent identifier, description provides context for tool selectors, and color (optional) assigns a visual theme in supported interfaces.

H1 Title

Immediately following the frontmatter, the file must contain a level-one heading that matches the agent’s name for human readability.

# Frontend Developer Agent

Core Content Sections

The remainder of the document uses level-two headings (##) to define functional domains. While all sections are optional, robust agents typically include the standardized sections listed below to provide comprehensive behavioral context.

Key Sections for Agent Definition

The Agency-Agents specification recognizes several semantic H2 sections that map to specific behavioral controls:

🧠 Your Identity & Memory

This section defines role, personality traits, memory cues, and experience level. It establishes the agent’s voice and contextual awareness.

## 🧠 Your Identity & Memory

- **Role**: Weekly reporting specialist
- **Personality**: Concise, data-driven, friendly
- **Memory**: Remembers last week’s metrics and any open blockers

🎯 Your Core Mission

High-level objectives are broken into subsections (often H3) such as DX Engineering, Content Creation, or Community Building. This maps the agent’s strategic priorities.

🚨 Critical Rules You Must Follow

Non-negotiable constraints including ethics, quality standards, and response times. These act as guardrails that the conversion pipeline may extract for safety filtering.

📋 Your Technical Deliverables

Structured output templates the agent should produce, often using Markdown tables or fenced code blocks to define audit frameworks and tutorial skeletons.

🔄 Your Workflow Process

Step-by-step operational procedures (e.g., Project Setup → Development → Optimization → Testing) that guide the agent’s execution sequence.

📋 Your Deliverable Template

Boilerplate Markdown reports with placeholders for UI analysis, performance metrics, accessibility checks, and other domain-specific outputs.

💭 Your Communication Style

Tone and phrasing guidelines such as "Be precise" or "Focus on UX" that modulate the agent’s linguistic patterns.

🔄 Learning & Memory

Knowledge accumulation patterns where the agent records project-specific pitfalls, reusable patterns, and expertise focus areas across sessions.

🎯 Your Success Metrics

Quantitative KPIs (e.g., Lighthouse scores, load-time thresholds) and qualitative targets that define task completion criteria.

Conversion and Integration Workflow

Creating the Markdown file is only the first step. The repository provides automation to transpile these documents into active agent configurations.

Step 1: File Placement

Save your custom agent with a descriptive filename and .md extension in the appropriate category folder:

specialized/my-custom-agent.md
engineering/api-architect.md
design/ui-systems-specialist.md

Step 2: Run the Conversion Script

Execute scripts/convert.sh to parse all Markdown agents and generate tool-specific integration files:

./scripts/convert.sh

This script extracts frontmatter and section content to create configurations for Claude Code (~/.claude/agents/), Cursor (.cursor/rules/), and OpenCode (~/.config/opencode/agent/).

Step 3: Install for Your Target Tool

Deploy the generated artifacts using the install script:

./scripts/install.sh --tool cursor    # or claude-code, opencode, etc.

Complete Custom Agent Example

Below is a minimal yet functional custom agent following the Agency-Agents specification. This example demonstrates the required frontmatter, section hierarchy, and deliverable templates.

---
name: My Custom Agent
description: A lightweight agent that creates weekly status reports.
color: teal
---

# My Custom Agent

## 🧠 Your Identity & Memory

- **Role**: Weekly reporting specialist
- **Personality**: Concise, data-driven, friendly
- **Memory**: Remembers last week's metrics and any open blockers

## 🎯 Your Core Mission

- Collect team updates from Slack threads
- Summarize key achievements and blockers
- Produce a markdown report for the weekly meeting

## 🚨 Critical Rules You Must Follow

- **Accuracy**: Verify every metric against the source data
- **Brevity**: Keep the report under 500 words
- **Tone**: Positive but honest

## 📋 Your Technical Deliverables

### Weekly Report Template

```markdown

# Weekly Status – {{date}}

## Wins

- …

## Blockers

- …

## Metrics

| KPI | Current | Target |
|-----|---------|--------|
| …   | …       | …      |

🔄 Your Workflow Process

1. Pull latest sprint data from the project board.
2. Scan #team-updates channel for messages tagged #report.
3. Populate the template above.
4. Send the markdown to the #weekly-reports channel.

🎯 Your Success Metrics

• Report Accuracy: ≥ 98 %
• Delivery Time: Sent within 30 min after meeting start
• Stakeholder Satisfaction: ≥ 4.5/5 rating

Save this file as [`specialized/my-custom-agent.md`](https://github.com/msitarzewski/agency-agents/blob/main/specialized/my-custom-agent.md) and run [`./scripts/convert.sh`](https://github.com/msitarzewski/agency-agents/blob/main/./scripts/convert.sh) to generate the integration files.

## Summary

- **Agency-Agents** uses self-contained Markdown files (`.md`) as the canonical source for agent definitions, stored in category folders like `specialized/` and `engineering/`.
- **YAML frontmatter** (`name`, `description`, `color`) at the top of each file provides metadata for the conversion pipeline.
- **Standardized H2 sections** (Identity, Mission, Rules, Deliverables, Workflow, Metrics) structure the agent’s behavior and context.
- **Conversion workflow**: [`scripts/convert.sh`](https://github.com/msitarzewski/agency-agents/blob/main/scripts/convert.sh) parses Markdown into tool-specific configurations, while [`scripts/install.sh`](https://github.com/msitarzewski/agency-agents/blob/main/scripts/install.sh) deploys them to Claude Code, Cursor, or OpenCode directories.

## Frequently Asked Questions

### What file extension must a custom agent use?

Agency-Agents requires all agent definitions to use the `.md` (Markdown) extension. The [`scripts/convert.sh`](https://github.com/msitarzewski/agency-agents/blob/main/scripts/convert.sh) pipeline specifically scans for `*.md` files in category folders to parse frontmatter and content sections.

### Where should I save my custom agent file?

Place your custom agent in the appropriate category subdirectory based on its domain: `specialized/` for niche roles, `engineering/` for technical development agents, or `design/` for creative specialists. The conversion script recursively processes all `.md` files within these folders regardless of specific filenames.

### Which sections are mandatory in an agent Markdown file?

Only the **YAML frontmatter** (enclosed by `---`) and an **H1 title** are strictly required for the conversion pipeline to recognize the file. However, functional agents typically include `## 🧠 Your Identity & Memory`, `## 🎯 Your Core Mission`, and `## 🔄 Your Workflow Process` to provide sufficient behavioral context for the LLM.

### How do I activate my custom agent in Cursor or Claude Code?

After saving your `.md` file in the correct folder, run [`./scripts/convert.sh`](https://github.com/msitarzewski/agency-agents/blob/main/./scripts/convert.sh) to generate the tool-specific configuration files. Then execute `./scripts/install.sh --tool cursor` (or `claude-code`, `opencode`) to copy the generated rules into the target tool’s configuration directory (e.g., `.cursor/rules/` or `~/.claude/agents/`).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}