| name | wizard-evolve |
| description | How to extend Claude Code's own capabilities, Wizard-style. Use when asked to add a new capability, tool, skill, MCP server, or subagent to Claude Code itself — or when a task needs a capability the harness does not yet have (browser, database, computer use, a domain workflow). Pick the cheapest channel that works and verify it is live before reporting success. |
Self-extension (Wizard's /evolve, on Claude Code)
Wizard's prime directive: when a task needs a capability you do not yet
have, acquire it — don't complain about lacking it. Treat "I can't browse
the web", "I have no database tool", and "I can't see that format" as work
items. Refuse only after trying and hitting a wall you cannot pass (no
network, no toolchain, a missing credential you cannot obtain), and then say
exactly what you tried and what blocked you.
Add every new capability through the cheapest channel that works. All of
these are plain files the user can review, edit, or delete — keep each
evolution independently reversible.
Picking a channel
| The capability is… | Channel | Where it lives |
|---|
| Knowledge, a workflow, domain guidelines | Skill | ~/.claude/skills/<name>/SKILL.md (user) or .claude/skills/<name>/SKILL.md (project) |
| External (browser, computer use, database, search, cloud API) | MCP server | claude mcp add <name> -- <command> |
| Small glue or project automation | Scripted tool | An executable script plus a skill that says when to run it |
| A repeatable prompt the user fires by hand | Slash command | ~/.claude/commands/<name>.md or .claude/commands/<name>.md |
| A specialized sub-worker with its own prompt/tool scope | Subagent | ~/.claude/agents/<name>.md or .claude/agents/<name>.md |
| Automated behavior on harness events ("whenever X, do Y") | Hook | settings.json hooks |
Rule of thumb: if an MCP server or a script can do it, do that. It's
instant, reversible, and works on every install. Wizard's deepest rung —
recompiling its own binary — has no equivalent here (the binary is
Anthropic's); the deepest rung on Claude Code is authoring a plugin that
bundles skills, agents, commands, and MCP servers for others to install.
Channels
Skills
Write <dir>/skills/<name>/SKILL.md: --- frontmatter with name and
description, then a markdown body. The description decides when the
skill is surfaced — make it name the triggers ("Use when…"). Keep skills
focused and imperative: instructions, not essays.
MCP servers
Register with the CLI (project scope by default; --scope user to make it
global):
claude mcp add playwright -- npx -y @playwright/mcp@latest
This is the right channel for browser use — the canonical "build it"
example. When a task needs the web (reading pages, filling forms, clicking,
computer use), do not say you can't browse: register the Playwright MCP
server above, then use its navigate/click/type/snapshot tools. If
npx/Node is absent, install it, or fall back to a scripted curl fetch
for read-only tasks. Try the real thing before declaring it impossible.
The same pattern covers databases (a Postgres/SQLite MCP server), search,
and computer use. Verify the command (or url) actually exists on this
machine before registering it.
Scripted tools
Author a small, self-contained script (shell/Python/JS) somewhere stable
(~/.claude/tools/ is a good convention), make it executable, and pair it
with a skill or slash command that documents when to run it and with what
arguments. Print results to stdout and exit non-zero on failure. Test the
script once with Bash before declaring the evolution done.
Subagents
Write <dir>/agents/<name>.md:
---
name: reviewer
description: Audits diffs for security issues. Use after nontrivial changes.
tools: Read, Grep, Glob, Bash
---
You are a security reviewer. Examine the diff for injection, authz, and
secret-handling flaws. Report findings with file:line.
Keep tools as narrow as the job allows; a subagent runs in an isolated
context and returns one final report.
Hooks
For "whenever X happens, do Y" automation, add a hook to settings.json
(user or project). Hooks are executed by the harness, not by the model, so
they are the only channel that can guarantee an automated behavior.
Always
- Log every evolution by appending one JSON line to
~/.claude/evolution.jsonl ({"ts", "channel", "name", "path", "why"}),
and 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, confirm the capability is actually present
before reporting success:
claude mcp list for servers, /agents for
subagents, invoke the skill/command once for the rest. Skills, agents,
and commands are picked up on the next session start — say so if a
restart is needed.
- 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.
