# Commands and skills

Commands and skills are markdown files in your package. No code runs for them, and they need no permissions.

- A **command** is a shortcut the user types: `/research why is the build slow?` expands into a full instruction
  for the agent.
- A **skill** is a body of instructions (plus supporting files) an agent loads **only when it needs it**. The
  agent always sees the skill's key and one-line description; the full text costs context only when the agent
  decides to use it.

## Commands — `commands/<name>.md`

```markdown
---
description: Grounded, cited research — read the sources, and separate what was verified from what was inferred.
argument-hint: <question>
---

Send the question below to Librarian (research):

1. Search broadly first — the codebase, its docs and commit history, and external sources when relevant.
2. READ the sources that matter; never answer from a search snippet alone.
3. Return a structured answer with EXACT pointers: file:line, function names, URLs, commit hashes — whatever lets me verify without redoing the search.
4. Separate what was VERIFIED from what was inferred, and name the gaps that could not be closed.

Question: $ARGUMENTS
```

*(`infrastructure/plugins/oh-my-openagents/commands/research.md`)*

- **The file name is the command.** `commands/research.md` registers `/research`. Names match
  `^[a-z0-9][a-z0-9_-]{0,63}$`.
- **`description`** (required) — shown in the command menu.
- **`argument-hint`** (optional) — the placeholder shown after the name, e.g. `<question>`.
- **The body** (required, non-empty) is the template sent to the agent in place of what the user typed.

### Placeholders

| In the template | Replaced with |
| --- | --- |
| `$ARGUMENTS` | everything the user typed after the command name |
| `$1` … `$9` | the 1st … 9th whitespace-separated word (empty if missing) |

If the template uses none of them and the user typed something after the command, it is appended to the end of the
template as a new paragraph — a plain template still receives the user's words.

So `/research why is the build slow?` becomes the template above ending with
`Question: why is the build slow?`.

### Which agents get them

Commands appear on every agent of the account; each agent's **Access → Commands** can narrow the list. Command
names are **not** prefixed with your plugin's slug. Built-in commands (such as `/new`) keep their names, and if two
installed plugins both ship `/research`, the first one wins; the other is dropped. Pick distinctive names.

## Skills — `skills/<key>/skill.md`

```
skills/
  parallel-orchestration/
    skill.md
    references/
      routing.md
      verification.md
  root-cause-analysis/
    skill.md
```

`skill.md` (the file name's letter case doesn't matter; exactly one per folder):

```markdown
---
name: Parallel Orchestration
description: "The full conductor protocol for leading the crew: decompose by category, delegate in parallel, integrate, and finish on evidence. Includes the routing table and the done-checklist."
---

# Parallel Orchestration

The full conductor protocol for leading the Oh My OpenAgents crew. Your always-on doctrine is the short version;
load this skill when you are about to conduct real, multi-part work and want the complete method, the routing
table, and the verification checklist.

…

2. **Decompose by category.** … The full table is in `references/routing.md`.
```

*(`infrastructure/plugins/oh-my-openagents/skills/parallel-orchestration/skill.md`)*

- **The folder name is the skill's key** (`^[a-z0-9][a-z0-9_-]{0,63}$`).
- **`description`** (required) — what the agent reads to decide whether to load it. Write it as "when to use me".
- **`name`** (optional) — the display name shown in the console; defaults to the key. The agent sees and loads a
  skill by its **key**, not by this name.
- **Supporting files** — anything else in the folder, up to 100 files per skill, 256 KB each. Refer to them by
  relative path in `skill.md`.

### How an agent uses a skill

Every turn, the agent's system prompt carries a **Skills** section listing each available skill's name and
description. When the agent decides it needs one, it calls the built-in tools:

| Tool | Does |
| --- | --- |
| `use_skill(name)` | loads the skill's `skill.md` body into context and lists its supporting files (`name` is the skill's key) |
| `list_skill_files(skill)` | lists the supporting files |
| `read_skill_file(skill, path)` | reads one supporting file |

This is *progressive disclosure*: a 40-line doctrine can point to a 300-line playbook that is only read when it
matters. Oh My OpenAgents does exactly that — its always-on doctrine (injected by middleware) ends with *"load the
`parallel-orchestration` skill (use_skill) for the complete method"*.

Skills appear on every agent; **Access → Skills** can narrow them per agent. Like commands, skill names are not
prefixed — first installed wins on a clash. The skill tools disappear from an agent that has no skills enabled.

## Keys are shared across the package

Command names, skill keys and companion asset keys all live in one namespace per package: a command `research`
and a skill `research` in the same package refuse the publish.

## Combining with code

Commands and skills are most powerful next to code:

- A **command** routes a goal to a specialist your plugin created (`/research` → Librarian).
- **Middleware** adds a short always-on doctrine, and points to a **skill** for the long version.
- A **lifecycle event** keeps the agents those commands refer to alive.

See the [Oh My OpenAgents walkthrough](example-oh-my-openagents.md).