// Write a new SKILL.md to teach yourself a procedure for a recurring task. Use when asked to "write a skill", "create a skill", "add a skill", "remember how to X", "make a procedure for X", or when you notice a task pattern worth recalling in future sessions.
Answer questions about how 'mi' works, write new tools, or modify the harness. Use for "how do you work", "write a tool", "add a tool", "create a tool", "extend yourself", "edit yourself", "what tools do you have", or any introspection/modification of the running agent.
Scan the codebase and classify every fact by lifecycle stage — tag @draft, @spec, or @implemented based on what the code actually shows. Add missing facts, fix inaccurate ones, remove obsolete ones. Use when asked to discover facts, bootstrap or update a fact sheet, scan the codebase for truths, sync facts to match the code, or audit the fact sheet for accuracy.
Operate on @spec facts — implement them in code, then tag @implemented. Use when asked to implement facts, implement the spec, build from the fact sheet, make facts true, or work through unimplemented requirements.
Operate on @draft facts — collaboratively refine them into precise, actionable @spec facts. Resolve ambiguities, fill gaps, eliminate contradictions, and sharpen labels until every fact is ready to implement. Use when asked to refine facts, clarify the spec, review facts for quality, or "work on facts" with the user.
Manage .facts files — atomic, validatable truth statements about a project. Install, check, list, add, edit, remove, and lint facts via the CLI. ALWAYS read this skill when the user mentions facts in any capacity.
Answer "how does X work", "where is X defined", or "trace through Y" questions about a codebase using parallel subagent searches with cited summaries.
| name | new-skill |
| description | Write a new SKILL.md to teach yourself a procedure for a recurring task. Use when asked to "write a skill", "create a skill", "add a skill", "remember how to X", "make a procedure for X", or when you notice a task pattern worth recalling in future sessions. |
A skill is a SKILL.md with YAML frontmatter (name, description) and a procedural body. Skills teach procedures. For new capabilities (code that does something), write a tool instead — load the self skill for tool authoring.
Write a skill only when the task recurs, the procedure is non-obvious, and a description can match unseen phrasings. For one-off work, just do it. skill() first — never duplicate an existing skill.
Write to ~/.agents/skills/<name>/SKILL.md. <name> is kebab-case, ideally one short word, and unique against the existing list (skill()).
---
name: <kebab-case>
description: <one line — pack with the user phrasings that should trigger this skill>
---
<terse procedural body: trigger condition, then steps, concrete commands>
The description is the only thing visible during skill selection. Include the verbs and phrases a user is likely to say ("write X", "fix Y", "check Z"), not an abstract summary. If it doesn't match the user's words, the skill never loads.
The body is a procedure, not an essay. Lead with Use when… / Skip if…, then the steps. Aim for under 50 lines. Concrete bash commands beat prose. No preamble, no recap.
skill() to list — confirm nothing covers the task; read the closest match's body to be sure.<name>.mkdir -p ~/.agents/skills/<name> && cat > ~/.agents/skills/<name>/SKILL.md <<'EOF'
---
name: <name>
description: <intent-rich one-liner>
---
<body>
EOF
skill({name: '<name>'}) and check the body comes back. The harness reads disk on every call, so the new skill is loadable immediately. Do not skip this step — a typo in frontmatter silently breaks discovery.mi startup — /reset keeps the existing system prompt. Restart mi to pick up new skills automatically; until then the model can still load it by explicit name.