# How to Configure a Custom Agent in Everything Claude Code: Complete Guide

> Learn to configure a custom agent in Everything Claude Code. Follow our guide to create agent files, define tools and models, and register your agent for slash commands.

- Repository: [WorldFlowAI/everything-claude-code](https://github.com/WorldFlowAI/everything-claude-code)
- Tags: how-to-guide
- Published: 2026-09-07

---

**Create a Markdown file with a YAML header specifying `name`, `description`, `tools`, and `model`, then save it to the `agents/` directory and register it in [`plugin.json`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/plugin.json) to make your custom agent available via slash commands.**

Everything Claude Code is an open-source plugin that extends Claude's capabilities through **custom agents**—modular, Markdown-defined roles that control what Claude does, which tools it can access, and which model powers it. Configuring a custom agent lets you create reusable, specialized workflows without modifying core plugin code. This guide walks through the exact file structure, metadata syntax, and registration process used in the WorldFlowAI/everything-claude-code repository.

## What Is a Custom Agent in Everything Claude Code?

A **custom agent** is a declarative configuration written in Markdown with a YAML frontmatter header. According to the source code in [`agents/planner.md`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/agents/planner.md) and related files, an agent definition consists of two parts:

- **Metadata header** (`---` block) — controls agent identity, capabilities, and compute
- **Instruction body** — the prompt Claude follows when invoked

Agents are discovered at startup by scanning the `agents/` directory and the [`.claude-plugin/plugin.json`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/.claude-plugin/plugin.json) manifest. Once loaded, they become invocable as sub-agents through slash commands like `/planner` or `/code-reviewer`.

## File Structure and Location

Everything Claude Code expects agent definitions in specific locations:

| Path | Purpose |
|------|---------|
| `agents/*.md` | Built-in agent source files shipped with the plugin |
| `~/.claude/agents/*.md` | User-local custom agents (auto-loaded on startup) |
| [`.claude-plugin/plugin.json`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/.claude-plugin/plugin.json) | Plugin manifest that explicitly lists agents to register |

The repository's `agents/` directory contains reference implementations including [`planner.md`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/planner.md) and [`code-reviewer.md`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/code-reviewer.md). These demonstrate the exact syntax your custom agents must follow.

## Step-by-Step: Creating a Custom Agent

### Step 1: Create the Markdown File

Create a new file in `agents/` or your local `~/.claude/agents/` directory. Use a descriptive filename with the `.md` extension.

```bash
touch agents/my-agent.md

```

### Step 2: Write the Metadata Header

Start with a YAML frontmatter block delimited by `---`. The header requires four fields:

- `name` — unique identifier used in slash commands (lowercase, hyphens allowed)
- `description` — one-line summary shown in help text
- `tools` — comma-separated list of permitted tools (`Read, Write, Bash, Grep`, etc.)
- `model` — Claude model to run (`opus`, `sonnet`, `haiku`, or specific versions)

Example header from the source analysis:

```markdown
---
name: my-agent
description: Generates README sections for new projects
tools: Read, Write, Bash
model: opus
---

```

### Step 3: Add the Agent Instructions

After the closing `---`, write the prompt that defines the agent's behavior. This plain text is sent to Claude when the agent runs. Structure it with clear steps, tool references, and output expectations.

```markdown
You are an expert technical writer.
Your task is to create a concise, well-structured **README** for a given project.

1. Ask the user for the project name and a short tagline.
2. Query the repository (using `Read`) for a `package.json` or `pyproject.toml` to infer the primary language.
3. Generate a markdown block that includes:
   - A title header (`# {{project_name}}`)

   - Badges for language, build status, and license
   - A short description using the tagline
   - Installation instructions based on the detected language  
4. Write the output to `README.md` (using `Write`).

```

### Step 4: Register the Agent

#### Option A: Plugin Manifest (for distributed agents)

Edit [`.claude-plugin/plugin.json`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/.claude-plugin/plugin.json) to include your agent file in the `agents` array:

```json
{
  "agents": [
    "agents/planner.md",
    "agents/code-reviewer.md",
    "agents/my-agent.md"
  ]
}

```

This registration method is used for agents bundled with the plugin itself, as seen in the official [`plugin.json`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/plugin.json) at [`.claude-plugin/plugin.json`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/.claude-plugin/plugin.json) in the repository.

#### Option B: Local Installation (for personal agents)

Copy your agent file to the local Claude configuration directory:

```bash
cp agents/my-agent.md ~/.claude/agents/

```

Files in this directory are automatically discovered without manifest modification.

### Step 5: Reload to Activate

Restart your Claude session or execute the reload command to pick up the new agent:

```bash
/my-agent

```

If configured correctly, Claude will execute your agent's instructions using the specified tools and model.

## Reference: Built-In Agent Implementation

The [`agents/planner.md`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/agents/planner.md) file in the repository demonstrates production-grade agent structure. Key patterns to follow:

- Keep descriptions under 100 characters for clean command listings
- List only tools the agent actually needs—excess permissions increase token usage and risk
- Use `opus` for complex reasoning, `sonnet` for balanced tasks, `haiku` for quick operations
- Structure instructions as numbered steps for predictable behavior

## Tool and Model Selection Guide

| Model | Best For | Typical Use Case |
|-------|----------|----------------|
| `opus` | Complex reasoning, multi-step planning | Architecture design, thorough code review |
| `sonnet` | General purpose, balanced cost/performance | Refactoring, documentation generation |
| `haiku` | Fast, simple tasks | File searching, quick edits |

Available tools include `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`, and others defined in the core plugin. Consult [`rules/agents.md`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/rules/agents.md) in the repository for guidance on selecting appropriate tools for your agent's workflow.

## Troubleshooting Custom Agent Configuration

- **Agent not appearing**: Verify the filename matches the `name` field, check JSON syntax in [`plugin.json`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/plugin.json), and confirm the file is in a scanned directory
- **Tool permission errors**: Ensure all tools referenced in instructions are explicitly listed in the `tools` header
- **Model not found**: Use exact model identifiers as documented in Claude's API reference

## Summary

- **Custom agents** in Everything Claude Code are Markdown files with YAML frontmatter defining `name`, `description`, `tools`, and `model`
- Save agents to `agents/` for bundled distribution or `~/.claude/agents/` for personal use
- Register agents in [`.claude-plugin/plugin.json`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/.claude-plugin/plugin.json) or rely on automatic directory scanning
- Write clear, step-by-step instructions in the body; reference tools with backticks
- Reload Claude to activate new agents, then invoke with `/your-agent-name`

## Frequently Asked Questions

### What file format does a custom agent use?

Everything Claude Code uses **Markdown with YAML frontmatter**. The `---` delimited header contains metadata; everything after is the instruction prompt. This format is human-readable, version-control friendly, and parses correctly in the plugin's agent loader.

### Where should I put my custom agent files?

Use `~/.claude/agents/` for personal agents that load automatically, or `agents/` with a [`plugin.json`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/plugin.json) entry for agents you want to bundle with the plugin. The repository's [`agents/planner.md`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/agents/planner.md) and [`.claude-plugin/plugin.json`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/.claude-plugin/plugin.json) show the official structure.

### Can I change which Claude model my agent uses?

Yes—set the `model` field in the header to `opus`, `sonnet`, or `haiku`. This controls which model handles the agent's requests independent of your main Claude session's configuration, letting you optimize cost and capability per task.

### How do I know if my agent is properly registered?

Run the help command or try invoking it with `/{your-agent-name}`. If Claude responds with your agent's behavior, it's registered. If you get an "unknown command" error, check the `name` field matches your invocation, verify [`plugin.json`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/plugin.json) syntax, and ensure the file path is correct relative to the manifest.