| name | self-healing |
| description | Update or upgrade the agent's own configuration on request — swap the model, add tools or MCP servers, change the image-generation provider/model, or install a new skill. Use when the user says things like "upgrade yourself", "switch your model to X", "use Gemini for images", "make yourself faster/smarter". |
Self-Healing Skill
Modifies on-disk agent configuration in response to user requests. All changes are surgical edits under {OPENAGENTD_CONFIG_DIR}/. No code changes, no restarts.
Agent configuration
The coding agent is always defined by {AGENTS_DIR}/code.md. MCP servers and
multimodal.yaml are global.
Scope
| Target | File | Example request |
|---|
| Model / params | Agent .md frontmatter | "switch to gpt-5" |
| Tools | Agent .md → tools: | "give yourself shell access" |
| MCP servers | Agent .md → mcp: or tools: | "let yourself use the filesystem MCP" |
| Image / video generation | {OPENAGENTD_CONFIG_DIR}/multimodal.yaml | "use Gemini for images" |
| New skills | {SKILLS_DIR}/{name}/SKILL.md | use skill skill-installer |
Workflow
- Identify the target file. Use
{AGENTS_DIR}/code.md.
- Read the current file.
- Compute the minimal diff — change only what was asked. Never reformat unrelated lines.
- Show a
diff block with a one-line summary.
- Wait for confirmation unless the request was already explicit — then apply in the same turn after showing the diff.
- Apply with
edit (preserves the file verbatim). Use write only for new files.
- Report what changed, which file, and when it takes effect.
When changes take effect
| Change | Takes effect |
|---|
Agent .md | Next turn of that agent (drift detection) |
mcp.json | After restarting the affected MCP server, on the next agent turn |
SKILL.md edited | Next turn of any agent using the skill |
| New skill installed | Immediately loadable by skill("name") |
multimodal.yaml | Instantly — read on every generate_image / generate_video call |
Process restart required only for: adding/removing agent files, .env changes, and code changes.
Agent frontmatter — valid fields
| Field | Values |
|---|
model | provider:model — e.g. openai:gpt-4o, anthropic:claude-..., googlegenai:gemini-... |
tools | Extra tools on top of built-in profile: web_search, web_fetch, read, patch, grep, glob, shell, generate_image, generate_video, plus <server>_<tool> for MCP. Never add skill — injected automatically. |
Invariants: model must contain :.
Recipes
Find your own agent file
printf '%s\n' {AGENTS_DIR}/code.md
Setting up multimodal.yaml
When generate_image / generate_video returns "not configured", or the user explicitly asks.
- Pick a provider (user-specified, or default to
openai:gpt-image-2 / googlegenai:veo-3.1-generate-preview).
- Write immediately — don't check env vars first. If a key is missing the tool returns a clear error; relay it then.
- Retry the original generation request after writing.
MCP tools on agents
mcp: list (recommended) — grants all tools the server exposes:
mcp:
- filesystem
tools: list (selective) — pick specific tools:
tools:
- filesystem_read
Verify the server is ready before wiring:
curl -sS http://localhost:4082/api/mcp/servers/<name> | jq '{state, tool_names}'
When removing a server: strip it from agent .md files first, then edit mcp.json — otherwise the agent logs agent_config_refresh_failed on its next turn.
Failure modes
- File not found → ask the user to confirm the path / agent name.
- Malformed frontmatter → show the problem; don't attempt repair unless asked.
- Invariant violation (two leads, unknown tool, unsupported provider) → explain and suggest the nearest valid alternative.
