Configuration | Agent Farm

Start with a name

A profile points to an agent.

A profile is the entry point you select in the picker or pass to agent-farm run. Its YAML names the agent. Model settings, skills, and instructions belong in the agent file.

profiles/planner.yaml

agent: planner

Inside an agent.md file

Define the worker.

This annotated example follows the bundled planner. Save agent definitions as Markdown; the filename is their identifier. Use a model your installed harness and account support.

agents/planner.md

---
harness: claude                    # Native CLI to launch
model:
  name: claude-fable-5-1            # Model selected by this agent
  reasoning: high                  # Thinking effort
skills:
  - create-ticket                  # Shared skill directory names
  - explain-visually
description: Discuss intent and create actionable tickets and briefs.
subagents:
  socrates:                        # Name the parent uses to delegate
    agent: socrates                 # Another file: agents/socrates.md
    mode: native                   # Delegate through the same harness
---

You are the issue-creation identity using dcouple/skills.
Use the bundled create-ticket skill to discuss work, preserve intent,
and create or update GitHub issues and Grain briefs when authorized
by the user. Follow its Socrates review and finalization gates.
Begin with the user's request. Keep this session focused on discussing
intent and creating tickets.

harness: claude or codex: the native CLI that executes the work.
model: The model name and reasoning effort for this agent. Availability depends on your native harness and account.
skills: Directory names from your shared skills/ library. Each contains a SKILL.md playbook.
description: A short description of the agent’s job.
subagents: Explicit bindings to other agent files. Each needs a mode: native uses harness delegation; process launches a separate configuration and supports cross-harness children.
Markdown body: The instructions the agent follows. Optional instructions_files can prepend shared instructions.

Install the bundled plugin with agent-farm init to get this planner’s referenced skills and Socrates child. Native child declarations support one level. See the full configuration reference for supported fields and formats.

Add project connections

A toolbox you can take along.

Replace the example URL with your provider’s real MCP endpoint. auth: native keeps sign-in in Claude Code or Codex; the optional description tells your agent what the connection is for.

workspaces/my-project.yaml

instructions: |
  Use the project associated with this workspace.
connections:
  project-tools:
    type: mcp
    url: https://YOUR-MCP-SERVER.example/mcp
    auth: native
    description: Query the tools for this project.

agent-farm mcp login project-tools --workspace my-project --harness claude
agent-farm run planner --workspace my-project

Your native harness stores credentials. Connect local stdio servers with command and args, and inherit environment variables by name through env_vars. Read the local server examples.

Check your setup

See what will be loaded.

Inspect and diagnose

agent-farm inspect planner --workspace my-project
agent-farm doctor

inspect shows the resolved graph, settings, and source paths. Check live connections in your native harness’s MCP view.

Across repositories

Keep useful skills close.

Install a profile’s top-level skills into your native user skill directory for use across repositories.

Load, check, and remove managed skills

agent-farm set global planner --harness claude
agent-farm status global --harness claude
agent-farm unset global planner --harness claude

Unloading removes managed skill links while retaining the source files. Read how native skill layouts are generated.

Share a library

Package your setups.

Plugins distribute versioned profiles, agents, skills, and supporting resources. Update the bundled configuration after updating your CLI checkout. Updates flag conflicts with local edits.

Install the bundled configuration

agent-farm plugin install

For a custom source, use agent-farm plugin validate /path/to/config before agent-farm plugin install /path/to/config.

For scripted work

Run from a script.

Use --exec with a starting message for a headless run.

Run a task headlessly

agent-farm run implementer --exec \
  --message "Fix the failing tests"

Launch defaults: Claude --dangerously-skip-permissions; Codex --yolo. Review the launch permissions before automating a task.

Next / Find your fitWhere Agent Farm fits.