Agent Skills#

Agent skills let MiMo Code discover reusable instructions from your repo or home directory. Skills are loaded on-demand via the native skill tool—agents see available skills and can load the full content when needed.

#Place files

Put a SKILL.md inside a folder. The skill's name comes from its frontmatter—not the folder name—and SKILL.md files are discovered recursively, so you can nest them however you like.

MiMo Code searches these locations:

• Project config: .mimocode/skills/**/SKILL.md (the singular skill/ folder also works)
• Global config: ~/.config/mimocode/skills/**/SKILL.md
• Project compatibility dirs: .claude, .agents, .codex, and .opencode—each scanned at skills/**/SKILL.md
• Global compatibility dirs: the same four folders under ~/ (e.g. ~/.claude/skills/**/SKILL.md)

Add more sources with the skills.paths and skills.urls config options.

#Understand discovery

For project-local paths, MiMo Code walks up from your current working directory until it reaches the workspace root. Along the way it loads any matching skills/**/SKILL.md (or skill/**/SKILL.md) in .mimocode/, and skills/**/SKILL.md in the .claude, .agents, .codex, and .opencode directories.

Global definitions are also loaded from ~/.config/mimocode/ and from the same compatibility folders under your home directory (e.g. ~/.claude/skills/**/SKILL.md).

If two skills resolve to the same name, the last one loaded wins and a warning is logged.

#Write frontmatter

Each SKILL.md must start with YAML frontmatter. Only these fields are read:

• name (required)
• description (required)
• hidden (optional boolean—when true, the skill is loaded but kept out of the available-skills list)

Any other frontmatter fields are ignored.

#Name your skill

MiMo Code does not enforce a format on name or a length on description, but the name is how an agent references the skill, so keep it short and predictable. We recommend lowercase alphanumerics with single hyphens, e.g. git-release.

Keep the description specific enough for the agent to choose the skill correctly—it is the only signal the agent sees before loading the full content.

#Use an example

Create .mimocode/skills/git-release/SKILL.md like this:

---
name: git-release
description: Create consistent releases and changelogs
---

## What I do

- Draft release notes from merged PRs
- Propose a version bump
- Provide a copy-pasteable `gh release create` command

## When to use me

Use this when you are preparing a tagged release.
Ask clarifying questions if the target versioning scheme is unclear.

#Recognize tool description

MiMo Code lists available skills in the skill tool description. Each entry includes the skill name and description:

<available_skills>
  <skill>
    <name>git-release</name>
    <description>Create consistent releases and changelogs</description>
  </skill>
</available_skills>

The agent loads a skill by calling the tool:

#Configure permissions

Control which skills agents can access using pattern-based permissions in mimocode.json:

{
  "permission": {
    "skill": {
      "*": "allow",
      "pr-review": "allow",
      "internal-*": "deny",
      "experimental-*": "ask"
    }
  }
}

Patterns support wildcards: internal-* matches internal-docs, internal-tools, etc.

#Override per agent

Give specific agents different permissions than the global defaults.

For custom agents (in agent frontmatter):

---
permission:
  skill:
    "documents-*": "allow"
---

For built-in agents (in mimocode.json):

{
  "agent": {
    "plan": {
      "permission": {
        "skill": {
          "internal-*": "allow"
        }
      }
    }
  }
}

#Disable the skill tool

Completely disable skills for agents that shouldn't use them:

For custom agents:

---
tools:
  skill: false
---

For built-in agents:

{
  "agent": {
    "plan": {
      "tools": {
        "skill": false
      }
    }
  }
}

When disabled, the <available_skills> section is omitted entirely.

#Troubleshoot loading

If a skill does not show up:

1. Verify SKILL.md is spelled in all caps
2. Check that frontmatter includes name and description
3. Ensure skill names are unique—a duplicate name is silently overridden (last one loaded wins)
4. Check permissions—skills with deny are hidden from agents