Adding Skills

A skill is a folder containing a SKILL.md file with instructions that Multi can load into the agent context. Skills let you encode project-specific workflows, team conventions, and reusable guidance.

Multi activating a skill inside a task to apply its guidance

Folder locations

Multi scans for skills in this order:

1. Project-level (project-specific skills):
   • .multi/skills
   • .agents/skills
2. User-level (reusable across projects):
   • ~/.multi/skills
   • ~/.agents/skills

Project-level skills override user-level skills with the same name.

Minimum skill structure

Each skill lives in its own directory with a file named exactly SKILL.md:

.multi/
  skills/
    my-skill/
      SKILL.md

Minimum valid skill.md

---
name: my-skill
description: A brief, clear description of what this skill does.
---

Instructions for the agent when this skill is activated.
- rule or guideline
- constraint or pattern
- verification step

Required frontmatter fields:

• name - lowercase, hyphen-separated (e.g., typescript-refactor)
• description - one sentence, specific to the workflow

Optional fields:

• license - e.g., MIT
• compatibility - e.g., multi

What to put in the body

The body (after frontmatter) is injected into the agent context when activated. Include:

• When to use the skill
• Rules and constraints
• Workflow steps
• Quality checks
• Repo-specific conventions

Optional resource folders

Multi recognizes these direct subdirectories:

• scripts/ - shell scripts or tools
• references/ - documentation or guides
• assets/ - images or other files

Example structure:

.multi/skills/typescript-refactor/
  SKILL.md
  scripts/
    lint.sh
  references/
    style-guide.md

Multi lists files only one level deep (no nested subdirectories).

Quick start example

Create .multi/skills/api-review/SKILL.md:

---
name: api-review
description: Review-focused guidance for API design changes.
---

Use this skill when reviewing API changes.

Checklist:
- verify correctness and edge cases
- check naming clarity and consistency
- confirm backward compatibility
- look for security or performance issues
- test with real client usage patterns

Common mistakes to avoid

Mistake	Wrong	Correct
Filename	skill.md, Skill.md	SKILL.md
Location	.multi/skills/SKILL.md	.multi/skills/my-skill/SKILL.md
Frontmatter	Missing --- delimiters	--- at start and end
Required fields	Only name	Both name and description

Recognition checklist

Multi recognizes a skill only if all of these are true:

• ✓ Located in one of the scanned folders
• ✓ Inside its own directory
• ✓ Contains a file named exactly SKILL.md
• ✓ Begins with valid frontmatter (---)
• ✓ Includes both name and description

If any fail, the skill is skipped.

Tips

• One focus per skill - Keep skills focused on a single workflow
• Project vs. personal - Use project-level for team conventions, user-level for personal preferences
• Stable names - Skill activation depends on the name field, so keep it consistent
• Keep it instruction-heavy - Focus on actionable guidance, not marketing