Skip to main content

Agent File Format

AgentUse agents are markdown files with a .agentuse extension. They consist of:
  1. Frontmatter - YAML configuration
  2. Agent Prompt - Agent instructions

Basic Structure

The agent name is automatically derived from the filename. You don’t need to specify it in the frontmatter.

Frontmatter Configuration

Required Field

string
required
The AI model to use. Format: provider:model-nameExamples:
  • anthropic:claude-opus-5
  • anthropic:claude-sonnet-5
  • anthropic:claude-haiku-4-5
  • openai:gpt-5.6
  • openai:gpt-5.4-mini
  • openai:gpt-5.4-nano
  • openrouter:z-ai/glm-5.3
You can also specify environment variable suffixes:
  • anthropic:claude-sonnet-5:dev (uses ANTHROPIC_API_KEY_DEV)
  • openai:gpt-5.6:prod (uses OPENAI_API_KEY_PROD)
  • openai:gpt-5.6:OPENAI_API_KEY_PERSONAL (uses specific env var)

Optional Fields

string
A concise description of the agent’s purpose.This appears in:
  • Tool descriptions when used as a sub-agent
  • CLI output when running the agent
  • Plugin events for logging
Best practices:
  • Keep under 80-120 characters
  • Be action-oriented
  • Focus on primary capability
object
MCP server configurations. Each server can have:
  • command + args: For stdio-based servers
  • url: For HTTP-based servers
  • env: Environment variables for the server
  • requiredEnvVars: Required environment variables (fail if missing)
  • allowedEnvVars: Optional environment variables to pass
  • disallowedTools: Array of tool names/patterns to exclude
  • auth: Authentication for HTTP servers
  • headers: HTTP headers for HTTP servers
array
List of sub-agent configurations. Each sub-agent can have:
  • path: Path to the agent file (required)
  • name: Optional custom name for the sub-agent
  • maxSteps: Optional maximum number of steps the sub-agent can take

MCP Server Integration

Connect to Model Context Protocol servers for external tools and data sources:

Agent Syntax - MCP Servers

See the complete reference for stdio servers, HTTP servers, environment variables, authentication, and tool restrictions.

Using Sub-Agents

Agents can delegate to other agents. All sub-agent paths are resolved relative to the parent agent file’s directory:
Sub-agents can be local files or HTTPS URLs. Remote agents must end with .agentuse extension.

Environment Variables

Environment variables configure API keys, behavior settings, and MCP server credentials.

Environment Variables Reference

See the complete reference for API keys, behavior control, MCP server configuration, and security best practices.

Runtime Customization

You can append additional prompts when running agents without modifying the agent file:
This is useful for:
  • Testing different approaches without editing files
  • Providing context-specific instructions
  • Reusing agents with slight variations
  • Quick experimentation

Examples

For a comprehensive collection of agent examples, including data analysis, code review, API integration, and more, visit the AgentUse Templates.

Project Structure and Path Resolution

Project Root Detection

AgentUse automatically detects your project root by searching upward for .git/, .agentuse/, or package.json.

Path Resolution

All paths (subagents, MCP server commands) are resolved relative to the agent file’s directory, ensuring portability.
See Agent Syntax - Subagents for complete path resolution examples.

Benefits of This Structure

  1. Portability: Share entire agent projects without breaking paths
  2. Organization: Clear separation of concerns
  3. Reusability: Utils and helpers can be shared across agents
  4. Version Control: Everything in one repository
  5. Environment Management: Single .env file for all agents

Validate Before You Run It for Real

A new agent has two things worth checking before it touches anything that matters. agentuse doctor checks the configuration: skills that don’t exist, skills with no grants, commands the agent’s own instructions mention but that it was never granted, and what the whole prompt costs per model request.
agentuse test checks the behaviour. It runs the agent end to end in mock mode: side effects are fabricated rather than executed, approval gates resolve automatically so the run finishes unattended, and stores are isolated from your real data.

Testing Agents

The full edit-test-inspect loop, mock scope, approval branches, and what mock mode does and does not prove.

Next Steps

Sub-Agents

Learn about delegating tasks to other agents

Agent Design Patterns

Best practices and patterns for building agents

Examples

See more agent examples