| name | evolve |
| description | How to extend Wizard's own capabilities via /evolve. Picking the cheapest tier, the four runtime channels (skills, MCP servers, scripted tools, subagents), and when a deep recompile is justified. |
Self-extension (/evolve)
When asked to give yourself a new capability, add it through the cheapest
tier that works. Tier 1 changes are plain files under ~/.wizard/, take
effect on /reload, and are reverted by deleting the file. Tier 2
(--deep) recompiles Wizard itself and should be rare.
Picking a tier
| The capability is… | Channel | Recompile? |
|---|
| Knowledge, a workflow, domain guidelines | Skill | No |
| External (computer use, browser, database, search) | MCP server | No |
| Small glue or project automation | Scripted tool | No |
| A specialized sub-worker with its own prompt/budget | Subagent | No |
| A change to Wizard's own built-in behavior or UI | Deep (--deep) | Yes |
Rule of thumb: if an MCP server or a script can do it, stay in Tier 1. It's
instant, reversible, and works on every install. Reach for --deep only
when the capability must live inside the binary.
Tier 1 channels
Skills
Write ~/.wizard/skills/<name>/SKILL.md: optional --- frontmatter with
name and description, then a markdown body that is injected into the
system prompt. Keep skills focused and imperative: instructions, not
essays. User skills shadow bundled ones with the same name.
MCP servers
Append a [[server]] block to ~/.wizard/mcp.toml:
[[server]]
name = "computer-use"
transport = "stdio"
command = "uvx"
args = ["mcp-computer-use"]
On /reload, Wizard connects and merges the server's tools into the
registry (name collisions become server__tool). Verify the command (or
url) actually exists on this machine before registering it.
Scripted tools
Author a script plus a TOML manifest, both in ~/.wizard/tools/. The
manifest is <name>.toml beside the script:
name = "mermaid-png"
description = "Render a mermaid diagram source file to a PNG"
script = "mermaid-png.sh"
[parameters]
type = "object"
required = ["input", "output"]
[parameters.properties.input]
type = "string"
description = "Path to the .mmd source file"
[parameters.properties.output]
type = "string"
description = "Path for the rendered PNG"
The tool receives its arguments as a single JSON object string in argv[1],
parsed inside the script (e.g. with jq). Print results to stdout and
exit non-zero on failure. Test the script once with execute before
declaring the evolution done.
Subagents
Write ~/.wizard/subagents/<name>.toml:
name = "reviewer"
description = "Audits diffs for security issues"
system_prompt = "You are a security reviewer. Examine the diff for injection, authz, and secret-handling flaws. Report findings with file:line."
max_steps = 15
Keep tool_scope as narrow as the job allows; subagents run with
auto-approval inside their isolated context.
Tier 2, deep evolve
Only when the change requires new Rust in Wizard's core (a new built-in
tool kind, a protocol change, a TUI panel). The pipeline: source checkout
at ~/.wizard/src (cloned on first use), just-in-time minimal Rust
toolchain if cargo is absent, propose a diff, approval, cargo build --release, then exec-replace the running process. If no toolchain or
source can be provisioned, fall back to Tier 1 and say so. Do not fail.
Always
- Every evolution is logged to
~/.wizard/evolution.jsonl; tell the user
what was added and where the file lives so they can review or delete it.
- One file (or one config block) per capability. Keep evolutions
independently reversible.
- After writing the files,
/reload and confirm the new capability is
actually present (skill in prompt, tool in registry) before reporting
success.
- Safety: MCP servers and scripted tools run with the user's privileges
and can make their own network and system calls. Prefer well-known
servers and small auditable scripts; never add a capability the user did
not ask for.
