Creating Custom Agents

Elftia supports two ways to create custom Agents: through the in-app UI, or by writing .claude/agents/*.md configuration files directly. Both approaches ultimately produce a Markdown-format Agent configuration file.

Creating via the UI

Steps

1. Open the Agent panel (Agent icon in the sidebar)
2. Switch to the "My Agents" tab
3. Click the "Create Agent" button
4. Fill in the following configuration fields:

Field	Description	Example
Name	Display name of the Agent	Frontend Code Reviewer
Description	One-sentence summary of the Agent's capabilities	Review React/TypeScript code quality
System prompt	Core instructions for the Agent (Markdown format)	See examples below
Model	LLM model or alias to use	main, background
Tool list	Allowed tools (leave empty = inherit all)	Read, Grep, Glob
Skills	Skills to auto-load	code-standards
MCP servers	Associated MCP servers	github-mcp
Permission mode	Tool execution security level	default

5. Click "Save" to finish

Choosing a Storage Location

When creating, you can choose where to save:

• Project level — saved to the current project's .claude/agents/ directory; available only in this project
• Personal level — saved to ~/.claude/agents/; available across all projects

Creating via File

Simply create a Markdown file in the .claude/agents/ directory. The filename becomes the Agent's identifier.

File Format

---
name: Agent Name
description: Agent description
model: main
permissionMode: default
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - ListDir
  - WebSearch
  - WebFetch
skills:
  - code-standards
---

This is the body of the system prompt (Markdown format).

The Agent will follow these instructions when executing tasks.

Full Field Reference

Field	Type	Default	Description
name	string	filename	Agent display name
description	string	empty	Agent description
model	string	main	Model selection (supports aliases)
permissionMode	string	default	Permission mode
tools	string[]	inherit all	Allowed tool allowlist
skills	string[]	none	Skills to auto-load

Configuration Examples

Example 1: Programming Assistant

Focused on coding tasks with full file system and shell access.

---
name: Full-Stack Programming Assistant
description: Full-stack development assistant, proficient in TypeScript/React/Node.js
model: main
permissionMode: acceptEdits
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - ListDir
  - WebSearch
  - WebFetch
  - spawn_agent
skills:
  - code-standards
  - architecture-index
---

You are a full-stack development assistant, proficient in TypeScript, React, and Node.js.

## Workflow

1. Understand the requirements first; ask clarifying questions if needed
2. Use Glob/Grep to find relevant code
3. Use Read to review key files
4. Formulate an implementation plan
5. Use Write/Edit to write code
6. Use Bash to run tests

## Coding Standards

- Follow the project's ESLint and Prettier configuration
- New files should not exceed 400 lines
- Use TypeScript strict mode
- Add JSDoc comments for public APIs

Example 2: Research Analysis Agent

Read-only mode, focused on information gathering and analysis.

---
name: Research Analyst
description: Gather information from the codebase and the web for in-depth analysis
model: main
permissionMode: plan
tools:
  - Read
  - Glob
  - Grep
  - ListDir
  - WebSearch
  - WebFetch
  - list_skills
  - read_skill
---

You are a research analyst skilled at gathering information from codebases and the web.

## Working Method

1. Carefully understand the research topic
2. Use Grep/Glob to search the codebase for relevant information
3. Use WebSearch to find external references
4. Use WebFetch to retrieve detailed web content
5. Synthesize all information into a structured analysis report

## Output Format

Use Markdown format for the report, including:
- Summary
- Key findings
- Detailed analysis
- Recommendations and conclusions

Example 3: Task Automation Agent

Uses background sub-Agents to process multiple subtasks in parallel.

---
name: Task Orchestrator
description: Break down complex tasks into subtasks and execute them in parallel
model: main
permissionMode: acceptEdits
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - ListDir
  - spawn_agent
  - Notify
---

You are a task orchestrator skilled at breaking complex tasks into parallelizable subtasks.

## Workflow

1. Analyze the task and identify subtasks that can run in parallel
2. Use spawn_agent to launch sub-Agents for each subtask
3. Collect the results from sub-Agents
4. Integrate the results and verify consistency
5. Use Notify to signal task completion

## Sub-Agent Principles

- Each sub-Agent is responsible for one well-defined subtask
- Prefer background mode (background: true) for parallel execution
- Equip sub-Agents with the minimum necessary tool set
- Set a reasonable maxIterations to avoid infinite loops

Tool Allowlist Configuration

The tools field controls which tools an Agent is allowed to use.

Available Tool Names

Tool	Description	Sensitivity
Read	Read file contents	Safe
Write	Write files	Sensitive
Edit	Edit files (find and replace)	Sensitive
ListDir	List directory contents	Safe
Glob	Filename pattern matching	Safe
Grep	Content search	Safe
Bash	Execute shell commands	Sensitive
WebSearch	Web search	Safe
WebFetch	Fetch web content	Safe
spawn_agent	Launch a sub-Agent	Sensitive
list_skills	List available skills	Safe
read_skill	Read skill content	Safe
Notify	Send desktop notifications	Safe
SessionsYield	End the Agent loop	Safe

:::tip Omit to inherit all tools If you do not set the tools field, the Agent inherits all available tools (including MCP tools). Only set an allowlist when you need to restrict the tool scope. :::

Model Alias Details

Alias	Behavior
main / inherit	Use the main model of the current session
background	Use the background model configured by the user in settings (typically a lightweight model such as Haiku)
sonnet	Replace the parent model's family name with sonnet (e.g. claude-3-opus → claude-3-sonnet)
opus	Replace the parent model's family name with opus
haiku	Replace the parent model's family name with haiku

The background model is suitable for:

• WebFetch content summarization
• Simple auxiliary tasks for sub-Agents
• Data processing that does not require high reasoning capability

Skill Association

List skill names in the skills field; their content is automatically injected into the system prompt when the Agent starts:

skills:
  - code-standards      # Project coding standards
  - architecture-index  # Project architecture index

Skill lookup order:

1. Project directory .claude/skills/<name>/SKILL.md
2. Personal directory ~/.claude/skills/<name>/SKILL.md
3. Plugin directory ~/.elftia/plugins/skills/<name>/SKILL.md
4. Built-in skills

Testing and Debugging

After creating an Agent, it is recommended to perform the following tests:

1. Basic conversation — confirm the Agent understands its role and capabilities
2. Tool calls — verify the tool allowlist is configured correctly
3. Permission confirmation — confirm the permission mode behaves as expected
4. Skill loading — check that skills are correctly injected into the system prompt
5. Boundary testing — attempt to have the Agent use an unauthorized tool and verify it is correctly denied

FAQ

Problem	Cause	Solution
Agent does not use the specified tools	System prompt does not guide their use	Explicitly state in the system prompt when to use which tool
Agent ignores the system prompt	User messages override the instructions	Use a more assertive system prompt; add keywords such as "must"
Skills not taking effect	Skill name is misspelled	Use the list_skills tool to confirm available skill names
File saved to the wrong location	Path is incorrect	Confirm the file is under .claude/agents/ or ~/.claude/agents/
YAML frontmatter parsing fails	Formatting error	Confirm --- delimiters are used and YAML syntax is valid

Related Links

• Built-in Agents — Reference the configuration of preset Agents
• Tool Permissions & Security — Detailed permission mode explanation
• Skill System — Create and manage skills