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

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 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 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 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	Plugin manifest that explicitly lists agents to register

The repository's agents/ directory contains reference implementations including planner.md and 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.

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:

---
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.

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 to include your agent file in the agents array:

{
  "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 at .claude-plugin/plugin.json in the repository.

Option B: Local Installation (for personal agents)

Copy your agent file to the local Claude configuration directory:

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:

/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 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 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, 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 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 entry for agents you want to bundle with the plugin. The repository's agents/planner.md and .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 syntax, and ensure the file path is correct relative to the manifest.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}