Building

Commands and skills

Ship slash commands and on-demand instructions as plain markdown files — no code.

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 name and one-line description; the full text costs context only when the agent decides to use it.

Commands — commands/<name>.md

---
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

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 — if two installed plugins both ship /research, the first one wins, so 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):

---
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; defaults to the key.
• 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:

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.