AGENT.md File Format

Overview

AGENT.md is the declarative configuration file for Fleet agents. Each agent has an AGENT.md file in its folder that defines its identity, model, permissions, and behavior.

Location: ~/Library/Application Support/com.usefamiliar.desktop/agents/<agent-name>/AGENT.md

The file uses YAML frontmatter for configuration, followed by a markdown body that becomes the agent's system prompt.

---

File Structure

---
name: my-agent
description: What this agent does
model:
  provider: anthropic
  model: claude-sonnet-4-20250514
# ... other configuration fields
---

You are my-agent. Your purpose is...

## Instructions

1. Do this first
2. Then do that

---

Configuration Fields

Identity

Field	Type	Required	Description
name	string	Yes	Unique identifier for the agent
description	string	Yes	Brief description of the agent's purpose
is_core	boolean	No	If true, agent cannot be deleted (built-in agents)

Model Configuration

model:
  provider: anthropic
  model: claude-sonnet-4-20250514
  reasoning_level: medium

Field	Type	Required	Description
model.provider	string	Yes	AI provider: anthropic, openai, google, openrouter, ollama, lmstudio, custom
model.model	string	Yes	Model identifier (e.g., claude-sonnet-4-20250514, gpt-4o)
model.reasoning_level	string	No	Reasoning effort: none, low, medium, high

Tools

tools:
  - Read
  - Write
  - Bash

Field	Type	Default	Description
tools	string[]	All tools	List of tools this agent can use. Empty array means all tools are available.

See Tools Reference for available tools.

Parameters

Parameters define inputs the agent accepts when invoked via CLI, triggers, or API.

parameters:
  - name: project_path
    type: path
    required: true
    description: Path to the project to analyze
  - name: verbose
    type: boolean
    default: false
    description: Enable verbose output

Field	Type	Required	Description
name	string	Yes	Parameter identifier
type	string	Yes	string, path, number, or boolean
required	boolean	No	Whether the parameter must be provided
default	any	No	Default value if not provided
description	string	No	Human-readable description

Parameters are substituted into the system prompt using {{parameter_name}} syntax.

Trigger Bindings

Connect the agent to triggers for automated execution.

triggers:
  - trigger: file-watcher
    params:
      directory: ""
    enabled: true

Field	Type	Required	Description
trigger	string	Yes	Name of the trigger definition
params	map	No	Parameter mapping. Supports {{body.field}} for webhooks
enabled	boolean	No	Whether this binding is active (default: true)

See Trigger Types Reference for trigger configuration.

Subagent Restrictions

allowed_subagents:
  - research-agent
  - code-reviewer

Field	Type	Default	Description
allowed_subagents	string[]	All agents	List of agents this agent can spawn. Empty means no restrictions.

Skills

enabled_skills:
  - code-review
  - documentation

Field	Type	Default	Description
enabled_skills	string[]	All skills	Skills this agent can use. Empty means all skills are available.

Permissions

Define security boundaries for the agent.

permissions:
  execution_tier: read_write
  directories:
    - path: ~/projects
      access: readwrite
    - path: /etc
      access: read
  network:
    - "*.github.com"
    - "registry.npmjs.org"
  rules:
    - "Bash(npm:*)"
    - "Bash(docker:*)"
  inherit_workspace: true

Field	Type	Description
execution_tier	string	Security tier: restricted, read_only, or read_write
directories	DirectoryPermission[]	Path-specific access permissions
network	string[]	Allowed domain patterns (e.g., *.github.com)
rules	string[]	Tool permission rules in Tool(pattern) format
inherit_workspace	boolean	Whether to inherit workspace permissions (default: true)

Directory Permission:

Field	Type	Description
path	string	Absolute or relative path
access	string	read or readwrite

See Execution Tiers and Permission Rules for details.

Secrets

secrets:
  - GITHUB_TOKEN
  - SLACK_WEBHOOK

Field	Type	Description
secrets	string[]	Vault secret names this agent can access

Secrets are substituted at tool execution time using {{vault:SECRET_NAME}} syntax. The agent never sees the actual secret values.

See Secure Vault for managing secrets.

Lifecycle Hooks

Execute scripts or spawn agents at specific points during execution.

hooks:
  - event: onStart
    action: script
    script: |
      echo "Agent starting..."
    captureOutput: true

  - event: beforeToolCall
    action: script
    filter:
      tools: [Bash]
    script: |
      # Validate command safety
      if echo '' | grep -qE 'rm\s+-rf'; then
        exit 1
      fi
    onFailure: abort

  - event: onStop
    action: agent
    agent: wrap-up
    prompt: |
      Session complete. Summarize what was done.

Field	Type	Required	Description
event	string	Yes	When the hook fires (see Hook Events)
action	string	Yes	script or agent
script	string	If action=script	Shell script to execute
agent	string	If action=agent	Agent to spawn
prompt	string	If action=agent	Prompt for spawned agent
filter	HookFilter	No	Conditions for when hook applies
blocking	boolean	No	Whether to wait for completion
timeout	integer	No	Max execution time in milliseconds (default: 30000)
onFailure	string	No	warn, abort, or ignore (default: warn)
captureOutput	boolean	No	Capture stdout as {{hook_output}}
enabled	boolean	No	Whether hook is active (default: true)
name	string	No	Optional name for logging

Hook Events:

Event	When It Fires	Blocking
onStart	Agent begins a conversation	Yes
onStop	Agent is about to return to user	Yes
beforeToolCall	Before any tool is invoked	Yes
afterToolCall	After a tool completes	No
onError	Agent encounters an error	No
beforeMessage	Before sending request to LLM	Yes
afterMessage	After receiving response from LLM	No

Hook Filter:

filter:
  tools: [Bash, Write]        # Only for these tools
  excludeTools: [Read, Glob]  # Skip for these tools
  workspaces: ["/home/user/projects/*"]

Script Exit Codes:

Code	Meaning	Effect
0	Success	Continue normally
1	Failure	Respect onFailure behavior
2	Skip	Skip the operation (e.g., skip tool call)

See Lifecycle Hooks for full documentation.

MCP (Model Context Protocol)

Connect to MCP servers for additional tools and resources.

mcp_servers:
  - github
  - filesystem

mcp_permissions:
  github:
    allowed_tools: ["*"]
    denied_tools: ["delete_repo"]
  filesystem:
    allowed_tools: ["read_file", "list_directory"]

mcp_approval_required:
  - github_create_issue
  - github_merge_pr

Field	Type	Description
mcp_servers	string[]	MCP servers this agent can access
mcp_permissions	map	Fine-grained permissions per server
mcp_approval_required	string[]	MCP tools requiring user approval

MCP Permission Fields:

Field	Type	Description
allowed_tools	string[]	Tools that are allowed ("*" for all)
denied_tools	string[]	Tools that are explicitly denied

See MCP Servers for configuration details.

Compaction Strategy

Control how conversation history is managed for long sessions.

compaction_strategy: summarization

Value	Description
none	No compaction; may run out of context
summarization	Summarize older messages (default)
truncation	Drop oldest messages

---

System Prompt

The markdown body after the frontmatter becomes the agent's system prompt. This is where you define the agent's personality, instructions, and behavior.

---
name: dev-assistant
description: Development assistant
model:
  provider: anthropic
  model: claude-sonnet-4-20250514
---

You are a development assistant specializing in TypeScript and Go.

## Your Capabilities

- Code review and improvement
- Bug fixing and debugging
- Documentation writing

## Guidelines

- Always run tests before committing
- Follow existing code style
- Ask for clarification when requirements are unclear

Template Variables

The system prompt supports template substitution:

Variable	Description
{{parameter_name}}	Parameter value passed to the agent
{{hook_output}}	Output captured from hooks with captureOutput: true
{{workspace}}	Current working directory

---

Complete Example

---
name: code-reviewer
description: Reviews code for quality, security, and best practices
model:
  provider: anthropic
  model: claude-sonnet-4-20250514
  reasoning_level: medium

tools:
  - Read
  - Glob
  - Grep
  - Bash

parameters:
  - name: file_path
    type: path
    required: true
    description: File or directory to review
  - name: focus
    type: string
    default: all
    description: Focus area (security, performance, style, all)

triggers:
  - trigger: pr-opened
    params:
      path: ""
    enabled: true

permissions:
  execution_tier: read_only
  directories:
    - path: ""
      access: read
  network:
    - "api.github.com"

secrets:
  - GITHUB_TOKEN

hooks:
  - event: onStart
    action: script
    script: |
      cd "" && git log --oneline -5
    captureOutput: true

  - event: onStop
    action: script
    script: |
      echo "Review completed at $(date)" >> ~/.familiar/logs/reviews.log
    blocking: false

mcp_servers:
  - github

mcp_permissions:
  github:
    allowed_tools: ["get_pull_request", "create_review_comment"]

compaction_strategy: summarization
---

You are a code reviewer. Your job is to review code for quality, security, and best practices.

## Focus Area: {{focus}}

{{#if hook_output}}
## Recent Git History
{{hook_output}}
{{/if}}

## Review Checklist

1. **Security** - Check for vulnerabilities, injection risks, exposed secrets
2. **Performance** - Identify bottlenecks, unnecessary operations
3. **Maintainability** - Assess readability, naming, structure
4. **Best Practices** - Verify error handling, edge cases, tests

## Guidelines

- Be constructive and specific
- Explain the "why" behind suggestions
- Prioritize critical issues over style preferences
- Provide example fixes when possible

---

Next Steps

• Create your first agent
• Learn about triggers
• Configure MCP servers
• Set up lifecycle hooks