Skills

Skills live on this machine — under your home, this repo, or a local plugin you installed. There is no remote skills catalog.

Where Matcha CLI looks

Higher rows win when two skills share a name:

Matcha CLI also walks .agents/skills/ (and commands/) at each tier, and every directory between cwd and the git root.

Flat *.md files under a commands/ directory become slash commands. The filename stem is the command name.

Add extra folders:

[skills]
paths = ["~/my-team-skills"]
ignore = ["~/my-team-skills/wip"]
disabled = ["wip-skill"]

paths and ignore are filesystem paths (~ expands). disabled is a skill **name**: it stays listed but is not invoked.

Write a skill

~/.matcha/skills/commit/SKILL.md

---
name: commit
description: Create well-formatted git commits following conventional commit standards. Use when the user wants to commit changes or asks for /commit.
---

# Git Commit Skill

1. Run `git diff --staged`
2. Summarize what changed and why
3. Commit with a conventional message

name is lowercase letters, digits, and hyphens (up to 64 characters). If you omit it, Matcha CLI uses the directory name. description is how automatic invocation decides to fire — write the trigger phrases.

Useful optional frontmatter: when-to-use, allowed-tools, argument-hint, user-invocable (default true), disable-model-invocation (slash-only when true).

Create one interactively: `/create-skill`

/create-skill

Matcha CLI asks for a name, a scope, and the workflow. **Project** writes <repo>/.matcha/skills/<name>/ (shareable in git). **User** writes ~/.matcha/skills/<name>/. The skill appears in the slash menu after a short reload.

Run a skill

Type / and the skill name:

/commit
/commit fix the build

Arguments after the name are passed into the skill. Browse the **Skills** tab with /skills (same extensions modal as /hooks and /plugins).

Name collisions

A built-in keeps the bare name (/login, /compact, …). A colliding skill stays available under a qualified name: local:, repo:, user:, or the plugin name:

/local:commit
/user:commit
/acme:login

The slash menu badges both rows (built-in vs skill · …). matcha inspect tags collisions as [collides with /login → /acme:login].

See what loaded

matcha inspect
matcha inspect --json

Each skill is labeled project, user, bundled, config, or plugin: <name>. Disabled skills stay listed with [disabled].

Bundled skills cache under ~/.matcha/bundled/skills/. They are never written into ~/.matcha/skills/. A same-named local, repo, or user skill overrides the bundled copy. A plugin skill of the same name does **not** override a native skill; use the qualified plugin:name form.

What is not available

• **Remote skills catalog** — no server-synced skill store to browse.
• A server source in matcha inspect would mean a managed workspace sync. That path is not a first-release channel.

What you should see