Agent Frontmatter Specification

CAMI agents are Markdown files with YAML frontmatter. The frontmatter defines agent metadata (name, version, description, class, specialty) while the Markdown body contains the agent prompt.

This specification follows the agent-architect v4.0 format.

Quick Reference

Minimal Agent:

---
name: backend
version: "2.1.0"
description: Back-end specialist for Node.js API development
---
Agent prompt content goes here...

Complete Agent:

---
name: backend
version: "2.1.0"
description: Back-end specialist for Node.js API development with database integration
class: technology-implementer
specialty: nodejs-api-development
tags:
  - backend
  - nodejs
  - api
  - database
use_cases:
  - Building RESTful APIs
  - Database schema design
  - Authentication systems
color: "#10b981"
model: claude-sonnet-4
---
Agent prompt content...

File Format

Structure

---
[YAML frontmatter]
---
[Markdown content]

Components:

1. Opening delimiter: ---
2. YAML frontmatter (metadata)
3. Closing delimiter: ---
4. Markdown content (agent prompt)

Parsing:

• First --- starts frontmatter
• Next --- ends frontmatter
• Everything after is content

Required Fields

name

Type: string

Required: Yes

Format: kebab-case (lowercase, hyphens)

Agent's unique identifier.

name: backend

Rules:

• Lowercase only
• Hyphens separate words (not underscores, spaces, or camelCase)
• Alphanumeric + hyphens only
• Must be unique within a source

Examples:

• backend
• api-gateway
• quality-assurance
• Backend (uppercase - invalid)
• api_gateway (underscore - invalid)
• API Gateway (spaces - invalid)

Used For:

• File naming: <name>.md
• CLI deployment: cami deploy -a backend
• MCP tool calls: agent_names: ["backend"]

version

Type: string

Required: Yes

Format: Semantic versioning ("X.Y.Z")

Agent version following semver.

version: "2.1.0"

Format: "MAJOR.MINOR.PATCH"

• MAJOR: Breaking changes to agent behavior
• MINOR: New features, backward-compatible
• PATCH: Bug fixes, improvements

Rules:

• Must be quoted (string, not number)
• Three numeric components separated by dots
• No v prefix
• No pre-release suffixes (for now)

Examples:

• "1.0.0"
• "2.1.0"
• "10.5.3"
• 1.0.0 (not quoted - invalid)
• "v2.1.0" (v prefix - invalid)
• "2.1" (missing patch - invalid)

Used For:

• Update detection (scan_deployed_agents)
• Version comparison (exact string match)
• Documentation (update_claude_md)

description

Type: string

Required: Yes

Format: One-sentence summary (50-100 chars)

Human-readable agent purpose.

description: Back-end specialist for Node.js API development with database integration

Guidelines:

• One sentence (no period at end)
• Focus on what agent does (not how)
• Include key technologies if relevant
• 50-100 characters (concise but descriptive)

Examples:

• Back-end specialist for Node.js API development
• Front-end expert for React and modern web UIs
• Visual design specialist ensuring aesthetic excellence
• Does backend stuff (too vague - avoid)
• Expert in building scalable, performant, production-ready... (too long - avoid)

Used For:

• Agent listings (list_agents)
• Documentation (update_claude_md)
• User selection (helps choose right agent)

Recommended Fields

class

Type: string

Required: No

Values: workflow-specialist, technology-implementer, strategic-planner

Agent's work style classification.

class: technology-implementer

Classes:

workflow-specialist (Task Automator):

• Executes well-defined processes
• High efficiency, low planning overhead
• Phase weights: 15% research, 70% execute, 15% validate
• Examples: deployer, tester, formatter

technology-implementer (Feature Builder):

• Balanced research and implementation
• Builds features using established patterns
• Phase weights: 30% research, 55% execute, 15% validate
• Examples: frontend, backend, database

strategic-planner (System Architect):

• Deep analysis before implementation
• Designs systems and makes architectural decisions
• Phase weights: 45% research, 30% execute, 25% validate
• Examples: architect, designer, security

Default: If omitted, balanced weights (30/50/20).

Used For:

• Agent-architect's workflow planning
• Phase weight calculation
• User-friendly names in UI

specialty

Type: string

Required: No

Format: kebab-case domain identifier

Specific domain or technology focus.

specialty: nodejs-api-development

Examples:

• react-development
• kubernetes-operations
• postgresql-database-design
• ui-ux-design
• security-architecture

Guidelines:

• kebab-case format
• Specific technology or domain
• Helps agent-architect understand focus

Used For:

• Future: Agent discovery by specialty
• Future: Recommending complementary agents

Optional Fields

tags

Type: array of strings

Required: No

Searchable keywords for agent discovery.

tags:
  - backend
  - nodejs
  - api
  - database
  - rest

Guidelines:

• Lowercase
• General-purpose keywords
• Technologies, domains, use cases
• 3-10 tags recommended

Used For:

• Future: Tag-based search
• Future: Agent recommendations

use_cases

Type: array of strings

Required: No

Specific scenarios where agent excels.

use_cases:
  - Building RESTful APIs
  - Database schema design
  - Authentication systems
  - API documentation

Guidelines:

• Specific scenarios (not generic)
• Start with verb (Building, Designing, Implementing)
• 3-5 use cases recommended

Used For:

• Documentation (update_claude_md)
• User selection guidance

color

Type: string (hex color)

Required: No

Format: "#RRGGBB"

Visual accent color for UI representation.

color: "#10b981"

Guidelines:

• Hex format with # prefix
• Quoted string
• Readable contrast with backgrounds

Examples:

• "#10b981" (green)
• "#3b82f6" (blue)
• #10b981 (not quoted - invalid)
• "green" (not hex - invalid)

Used For:

• Future: UI visualization
• Future: Agent cards/badges

model

Type: string

Required: No

Values: claude-sonnet-4, claude-opus-4, etc.

Recommended Claude model for this agent.

model: claude-sonnet-4

Values:

• claude-sonnet-4 - Default, balanced performance
• claude-opus-4 - Maximum capability for complex tasks
• claude-haiku-4 - Fast responses for simple tasks

Used For:

• Future: Model selection in Claude Code
• Future: Cost optimization

Complete Examples

Minimal Agent

---
name: qa
version: "1.0.0"
description: Quality assurance and testing specialist
---
You are the QA agent, specializing in testing and quality assurance.
**Your Role**:
- Write comprehensive test suites
- Identify edge cases and bugs
- Ensure code quality standards
**Workflow**:
1. Analyze requirements
2. Design test strategy
3. Implement tests
4. Verify coverage

Standard Agent

---
name: backend
version: "2.1.0"
description: Back-end specialist for Node.js API development with database integration
class: technology-implementer
specialty: nodejs-api-development
tags:
  - backend
  - nodejs
  - api
  - database
use_cases:
  - Building RESTful APIs
  - Database schema design
  - Authentication systems
---
You are the Backend Agent, an expert in Node.js back-end development.
## Core Competencies
- RESTful API design and implementation
- Database integration (PostgreSQL, MongoDB)
- Authentication and authorization (JWT, OAuth)
- API documentation (OpenAPI/Swagger)
- Error handling and logging
## Workflow
### Phase 1: Research (30%)
- Understand API requirements
- Review existing codebase
- Identify integration points
### Phase 2: Implement (55%)
- Design API endpoints
- Implement business logic
- Set up database models
- Add authentication
### Phase 3: Validate (15%)
- Write integration tests
- Document API endpoints
- Verify error handling
## Best Practices
- Follow REST conventions
- Use TypeScript for type safety
- Implement proper error handling
- Write comprehensive tests
- Document all endpoints

Advanced Agent

---
name: architect
version: "3.2.0"
description: Expert application architect specializing in system design and technology selection
class: strategic-planner
specialty: system-architecture
tags:
  - architecture
  - system-design
  - tech-stack
  - scalability
use_cases:
  - Designing system architecture
  - Technology stack selection
  - Scalability planning
  - Technical decision making
color: "#8b5cf6"
model: claude-opus-4
---
You are the Architect Agent, a senior application architect with deep expertise in system design, technology selection, and architectural decision making.
## Role & Responsibilities
As the Architect, you lead technical direction by:
1. **System Design**: Creating scalable, maintainable architectures
2. **Tech Stack Selection**: Choosing technologies that fit project needs
3. **Architectural Decisions**: Making and documenting key technical choices
4. **Scalability Planning**: Designing for growth and performance
5. **Technical Leadership**: Guiding development teams
## Three-Phase Methodology
### Phase 1: Research & Analysis (45%)
**Gather Requirements**:
- Business goals and constraints
- Performance requirements
- Scalability needs
- Team capabilities
- Budget and timeline
**Analyze Options**:
- Research technologies
- Evaluate trade-offs
- Consider alternatives
- Document decision criteria
**Deliverables**:
- Requirements document
- Technology comparison matrix
- Architecture decision records (ADRs)
### Phase 2: Design & Document (30%)
**Create Architecture**:
- System diagrams
- Component specifications
- Data flow designs
- Integration points
- Security architecture
**Technology Selection**:
- Choose frameworks and libraries
- Define tech stack
- Specify versions and dependencies
**Deliverables**:
- Architecture diagrams
- Technical specifications
- ADR documents
### Phase 3: Validate & Guide (25%)
**Review with Stakeholders**:
- Present architecture
- Address concerns
- Refine design
**Create Implementation Plan**:
- Break down into phases
- Identify dependencies
- Set milestones
**Deliverables**:
- Implementation roadmap
- Developer guidelines
- Migration plan (if applicable)
## Architectural Principles
1. **Simplicity**: Choose simple solutions over complex ones
2. **Scalability**: Design for growth from day one
3. **Maintainability**: Optimize for change
4. **Security**: Build security in, not bolt it on
5. **Performance**: Consider performance implications early
6. **Testability**: Design for automated testing
## Documentation Standards
Every architectural decision must be documented in an ADR:
```markdown
# ADR 001: Technology Stack for Backend API
## Status
Accepted
## Context
Need to choose backend technology for RESTful API...
## Decision
We will use Node.js with TypeScript and Express...
## Consequences
- Positive: ...
- Negative: ...
- Risks: ...
```
## Communication
- **Diagrams**: Use C4 model for architecture diagrams
- **ADRs**: Document all significant decisions
- **Specifications**: Clear, actionable technical specs
- **Code Comments**: Explain "why", not "what"
## Collaboration
Work closely with:
- **Product Owner**: Align architecture with business goals
- **Backend/Frontend Agents**: Guide implementation
- **Security Agent**: Ensure secure design
- **QA Agent**: Design for testability
---
You are thoughtful, methodical, and always consider long-term implications. Your goal is to create architectures that empower teams to build excellent software.

Validation Rules

Required Field Validation

CAMI validates all required fields on load:

✗ Error: Missing required field 'version' in backend.md
✗ Error: Invalid version format '2.1' in backend.md (must be X.Y.Z)

Tools:

• detect_source_state - Analyze source compliance
• normalize_source - Add missing fields

Format Validation

Name Format:

✗ Error: Invalid name format 'Backend_Agent' (must be kebab-case)

Version Format:

✗ Error: Invalid version 'v2.1.0' (remove 'v' prefix)
✗ Error: Invalid version '2.1' (must be X.Y.Z)

Uniqueness Validation

Within a source, agent names must be unique:

✗ Error: Duplicate agent name 'backend' in source 'official-agents'
  Found in: backend.md, backend-v2.md

Across sources: Duplicates are allowed (priority-based deduplication).

Migration

Adding Version to Old Agents

Before (non-compliant):

---
name: backend
description: Back-end specialist for Node.js
---

After (normalize_source adds "1.0.0"):

---
name: backend
version: "1.0.0"
description: Back-end specialist for Node.js
---

Update manually to actual version:

---
name: backend
version: "2.1.0"
description: Back-end specialist for Node.js
---

Adding Description Placeholders

Before:

---
name: api-helper
version: "1.0.0"
---

After (normalize_source):

---
name: api-helper
version: "1.0.0"
description: Agent for api-helper tasks (update this description)
---

Update manually with accurate description:

---
name: api-helper
version: "1.0.0"
description: API integration helper for external services
---

Best Practices

Versioning Strategy

When to bump version:

MAJOR (X.0.0):

• Agent behavior changes significantly
• Different workflow or methodology
• Incompatible with projects expecting previous behavior

MINOR (X.Y.0):

• New capabilities added
• Enhanced features
• Backward-compatible improvements

PATCH (X.Y.Z):

• Bug fixes in prompts
• Clarifications in instructions
• Typo corrections

Example:

1.0.0 → 1.1.0: Added database integration capability
1.1.0 → 1.1.1: Fixed typo in SQL examples
1.1.1 → 2.0.0: Changed from REST to GraphQL focus

Description Guidelines

Good descriptions:

• "Back-end specialist for Node.js API development"
• "Visual design expert ensuring aesthetic excellence"
• "Database architect specializing in PostgreSQL"

Poor descriptions:

• "Helps with backend stuff" (too vague)
• "Backend" (not descriptive)
• "Does API development, database design, authentication..." (too long)

Template:

[Role] specialist for [Technology/Domain] [Key Focus]

Class Selection

Choose workflow-specialist when:

• Agent follows well-defined process
• Minimal planning/research needed
• Execution-focused tasks
• Examples: deployer, formatter, test-runner

Choose technology-implementer when:

• Agent builds features
• Moderate research required
• Technology-specific implementation
• Examples: frontend, backend, mobile

Choose strategic-planner when:

• Agent makes high-level decisions
• Extensive research/analysis needed
• Architectural or design focus
• Examples: architect, designer, security

Related Documentation

• MCP Tools API Reference: Tools that parse frontmatter
• Configuration Reference: Source configuration
• .camiignore Patterns: Exclude non-agent files
• Working with Agents - Creating Agents: Create new agents

Last Updated: 2025-11-24