Agents in a plugin

An agent is a specialist that an AI coding tool can hand work to (a subagent in most AI tools). In Athenode an agent belongs to an plugin, which is a named bundle of what your AI tools work with: skills, agents, rules, MCP servers and plugin files. Each agent has instructions of its own and is used only when work is delegated to it, by your main AI agent or by a skill. The rules of a plugin are a different thing: one text that every agent follows, installed as AGENTS.md for many AI tools.

Part	What it holds
Name	1 to 64 characters: lowercase letters and digits, separated by single hyphens, such as payment-reviewer. The name is unique in the plugin, and skills and your AI tool call the agent by it.
Description	Required. Your AI tool reads the description to decide when to hand work to the agent, so say what the agent does and when to use it.
Instructions	The agent's prompt, in Markdown.
Settings	Options for one AI tool, such as the model the agent runs on, the tools it may use, its own MCP servers and its hooks.

You need the owner or editor role to change a plugin. A viewer can open an agent and read it. The roles and permissions page has the full list.

A plugin holds as many agents as you need.

Create an agent

Create an agent for a job you want done in a context of its own, such as reviewing every change to the web shop's payment code for security problems.

1. On the Plugins page, select the plugin's card. Its blueprint appears below the cards.
2. On the Agents part of the blueprint, select the add button (Add to Agents).
3. Enter the Name and the Description. A description such as "Reviews changes to payment code for security issues. Use after changing the checkout flow." tells the AI tool when to delegate.
4. Select Create agent. The inspector shows Agent created and opens the agent.
5. On the Instructions tab, write the agent's instructions in Markdown and save them.

The agent appears in the Agents part of the blueprint. Without any settings it uses each AI tool's default model and tools, and the inspector says so: Uses each tool's default model and tools.

Edit an agent's instructions

Select an agent in the Agents part of the blueprint to open it in the inspector. The name and the description are edited in place at the top, and the Instructions tab holds the prompt without frontmatter. The frontmatter is the block of settings at the top of the installed agent file, and Athenode writes it from the name, the description and the Settings tab.

Renaming an agent changes the name that skills use to call it. A skill that names the agent in its instructions needs the same change.

Set an agent's model, tools and other options

The Settings tab holds options that are written into the installed agent file. They are set per AI tool, because each tool defines its own options for a subagent. GitHub Copilot, Google Antigravity and Kiro have two entries each, one for the editor and one for the command-line tool. The Common entry holds the description.

1. On the Settings tab, select the AI tool. Filter AI tools narrows the list by name.
2. Select Add field and pick a field from the ones that tool reads.
3. Enter the value. Depending on the field it is text, a number, an on or off switch, a choice from a list, a list of values, or JSON.

The fields differ by tool. These are the kinds you meet most:

Kind of field	Examples	What it sets
Model	model, active_model	Which model the agent runs on. Some tools offer a fixed list that includes inherit, which uses the model of the main agent.
Tools	tools, allowed-tools, disallowedTools	Which tools the agent may or may not use. Many AI tools have a field of this kind.
Reasoning effort	effort, model_reasoning_effort, reasoningEffort	How much reasoning the model spends on a task.
Permissions	permissionMode, sandbox_mode, readonly	What the agent may do without asking, or whether it may change files at all.
Limits	maxTurns, timeoutMins	When the agent stops.
MCP servers	mcpServers, mcp_servers	MCP servers that only this agent uses.
Hooks	hooks	Actions that run when the agent reaches an event.

After you set a model or tools, the blueprint shows the model next to the agent's name together with the number of tools. To take an option away, remove its field and confirm Remove field?.

Give an agent its own MCP servers

An agent can use MCP servers that the rest of the plugin does not get, such as a database server that only a migration agent needs. Servers that every agent should have belong to the plugin, as MCP servers in a plugin describes.

For Claude Code, the server list has a form:

1. On the Settings tab, select Claude Code and add the field mcpServers.
2. Select Add MCP server and enter the Server name.
3. Choose the Mode. Reference by name reuses a server that is configured under that name already and stores nothing else. Inline definition describes a server for this agent alone.
4. For an inline definition, choose the Type: stdio for a server your AI tool starts on your machine, or http, sse or ws for a server it reaches at a URL.
5. Enter the Command, Args and Env for stdio, or the URL and Headers for the other types.
6. Optional: under Advanced, set a Headers helper command that produces the request headers, a Timeout (ms), Always load, and the OAuth values Client ID, Callback port and Scopes.
7. Select Save.

Write tokens and keys as ${VAR} references, such as ${GITHUB_TOKEN}, and set the variable in the environment where your AI tool runs.

Other AI tools that give an agent its own servers have a field for them on their own entry of the Settings tab. For Google Antigravity, JetBrains Junie, Factory Droid, ZCode, Qwen Code and Zoo Code the value is a list of server names. For Codex, GitHub Copilot CLI, Kiro CLI and Qoder it is a definition in JSON.

Add hooks to an agent

A hook runs a command, an HTTP request, an MCP tool or a prompt whenever the agent reaches an event. A hook can, for example, run a script that checks each shell command before the agent runs it. For Claude Code, hooks have a form:

1. On the Settings tab, select Claude Code and add the field hooks.
2. Select Add hook and choose the Event, such as PreToolUse, PostToolUse or Stop.
3. Optional: enter a Matcher to limit the hook to some tools, such as Bash or Edit|Write.
4. Under Handlers, choose the handler's type and fill in its fields. Add handler adds another handler to the same hook.
5. Select Save.

Handler type	Fields
command	Command, Args, and under Advanced the Shell, Async and Async rewake
http	URL, Headers, Allowed env vars
mcp_tool	Server, Tool, Input
prompt	Prompt, Model
agent	Prompt

Every handler also has, under Advanced, If (condition), Timeout (ms), Status message and Run once.

Kiro CLI, Qoder and Qwen Code have a hooks field too, on their own entries of the Settings tab, with the value in JSON.

Remove an agent from a plugin

Open the agent, open its menu and select Delete. The dialog Remove agent from plugin? names the agent. After you confirm, the agent leaves this plugin. If no other plugin of the project uses it, it is deleted, which cannot be undone. Other plugins that use the agent keep it.

The built-in skills of the standard Athenode plugin call its 10 agents by name, so removing or renaming one of those agents stops the skills that use it from working. Athenode updates a built-in agent of your project's copy of the standard plugin only while you have not changed it.

Use the plugin's agents in your AI tool

Agents reach your repository when you install the plugin with init, and again each time you run init after changing the plugin in the web UI.

athenode init

For most AI tools every agent becomes one file named after the agent, with the settings at the top and the instructions below. Cursor, for example, reads .cursor/agents/payment-reviewer.md. In a tool that receives the plugin as a plugin package, such as Claude Code, the file is inside the plugin package. A few tools keep subagents differently:

• For Zoo Code, IBM Bob and Pool an agent is an entry in a configuration file that also holds your own entries. Athenode adds, updates and removes its own entries and leaves yours alone. If you have an entry with the same name, the plugin's agent is listed under "Not installed" in the plan that init shows.
• For Reasonix an agent is installed as a skill. An agent with exactly the name of a skill in the plugin is listed under "Not installed".
• Pool has a built-in agent called general, so a plugin agent of that name is listed under "Not installed" for Pool.

The files installed per tool page gives the path for each of the 30 supported AI tools.

Change an agent in the plugin and not in the repository, because the next install overwrites the installed file. init flags a file you edited locally before it does.

Manage agents from your AI tool

From your AI tool, ask /atn:manage to list, create, change or remove an agent. It works on the installed plugin unless you name another, and it updates the installed files itself.

Your AI agent reaches the same actions through the tools agents_list, agents_create, agents_update and agents_remove of the Athenode MCP server.

Ready-made agents are also part of the plugins that other projects publish. You can read them in the plugin library catalogue and add or merge them as the plugin library page describes.