Creating Agents

Creating Agents

Agents are isolated agentic mini-loops with their own model, tool whitelist, and instruction file (AGENT.md). Use agents when you need to delegate a self-contained task to a separate LLM context — typically work that benefits from a different model, a restricted tool set, or clean isolation from the main conversation.

Skill vs Agent — When to Use Which

| Use a skill (skills/) | Use an agent (agents/) | |-----------------------------|------------------------------| | Instruction to load into the main context | Isolated task with its own model | | No tool calls needed, or shares main tool set | Needs a restricted tool whitelist | | Workflow guidance or persona adjustment | Sub-task that returns a single result | | Lives in skills//SKILL.md | Lives in agents//AGENT.md |

Agent File Format

---
name: agent-name          # lowercase letters, numbers, hyphens only
description: One sentence — when to invoke this agent and what it returns.
model: provider/model-id  # required: the model this agent uses
tools: [tool1, tool2]     # required: exact tool names the agent may call
max_iterations: 5         # optional: default is global max (25)
tags: [tag1, tag2]        # optional
---

# Agent Name

(Instructions the agent follows. Starts with what it should do on first call.)

## Protocol

1. Step one
2. Step two
3. Return final answer

Tool Names

Tools must be the exact runtime names visible to the agent:

| Category | Name format | Example | |----------|-------------|---------| | Built-in | plain name | read_file, write_file, execute_command | | Skill tools | plain name | read_skill_file, write_skill_file, reload_skills | | Agent tools | plain name | read_agent_file, write_agent_file, reload_agents | | MCP tools | mcp_{server}_{tool} | mcp_google-workspace_query_gmail_emails |

read_skill_file and read_agent_file are always available to every agent — no need to list them.

Step-by-Step: Create a New Agent

1. Design — What model? What tools? What does it return?
2. Write the AGENT.md using write_agent_file:

`` write_agent_file(agent_name="my-agent", relative_path="AGENT.md", content="...") ``

1. Reload to activate immediately:

`` reload_agents() ``

1. Test by invoking:

`` invoke_agent(agent="my-agent", prompt="") ``

Calling Agents

invoke_agent(agent="agent-name", prompt="Task description here")

Optional overrides for one-off invocations:

invoke_agent(agent="agent-name", prompt="...", model="anthropic/claude-sonnet-4-6", tools=["read_agent_file", "mcp_threads_post"])

Example: Minimal Agent

---
name: summariser
description: Summarises a block of text into 3 bullet points. Invoke when the user asks for a summary.
model: qwen/qwen3-235b-a22b
tools: []
max_iterations: 2
---

# Summariser

Read your instructions (already loaded), then summarise the text in the prompt into exactly 3 bullet points. Return only the bullets — no preamble.

Existing Agents

Check agents/ for current agents. Use reload_agents after any changes to activate them.

Backward Compatibility

Skills with a model: field in skills/ still work via invoke_agent — the agent registry is checked first, then the skills registry. New agents should go in agents/.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: chinkan
• Source: chinkan/RustFox
• License: MIT

Install and usage instructions live in the source repository linked above.