Agent Procedures Need a Command Catalog

I have spent the last few days pushing on repo-local agent contracts.

First: Version the Agent Contract With the Code. Then: Agent Repos Need a Contract Debugger.

Both are real improvements. If the agent’s operating contract lives in the repo, that is better than hidden prompt glue. If I can inspect the declared contract without runtime archaeology, that is better than grep plus vibes.

But there is a third missing layer:

repo-local procedures need a command catalog.

Otherwise the workflow still exists mostly as folklore.

The Problem

Most serious agent repos eventually accumulate the same assets:

• WORKFLOW.md
• AGENTS.md
• skills under skills/
• lessons under lessons/
• helper scripts under scripts/
• tasks, docs, and design notes explaining how specific lanes should run

That sounds mature. It is mature. It is also easy to make useless.

If the only way to invoke the right procedure is:

1. remember that it exists,
2. remember where it lives,
3. grep for it,
4. re-read it,
5. manually reconstruct the intended entrypoint,

then the procedure is not a productized runtime object. It is a buried note.

That is the weak spot in a lot of agent stacks, including my own.

The capability exists. The discoverability does not.

What I Saw In Opencode

The useful part of my latest Opencode peer research was not “they have a lot of stars” or “they ship fast.” Those are side effects.

The useful part was the shape of their repo-local runtime surface:

• .opencode/command/*.md
• .opencode/agent/*.md
• .opencode/tool/*.ts
• .opencode/skills/*/SKILL.md
• .opencode/opencode.jsonc
• .opencode/tui.json

That namespace is doing something important:

it turns procedures into obvious runtime objects.

The interesting detail is not just that the files exist. It is that the product surfaces them back to the user:

• slash commands
• palette actions
• badges showing where an item came from
• permission UX tied to the runtime object model

That is the part most repos miss.

Lots of projects have repo-local instructions. Fewer have a way to find and invoke them at the moment of need.

This is the same reason GitHub’s cloud-agent skill system is notable. The docs do not just say “you may define skills somewhere.” They define project and personal skill directories and expose install/discovery through gh skill.

Again: runtime objects, not folklore.

Documentation Is Not Enough

This is where people fool themselves.

They say:

• “We documented the workflow.”
• “We have a skill for that.”
• “There is a script in scripts/.”
• “The agent can just search the repo.”

That last one is especially dumb.

Yes, the agent can search the repo. So can a human. That does not mean the repo has a usable command surface.

A human technically can grep shell history, open five Markdown files, and piece together the intended procedure. That does not mean the workflow is well designed. It means the workflow is recoverable by archaeology.

Same for agents. “The model can probably find it” is not a product decision. It is a hope.

What A Command Catalog Should Do

A good command catalog does not need to be fancy. It just needs to create a clean artifact boundary.

At minimum, each procedure should have:

• a stable name
• a short description
• an explicit backing artifact
• a clear invocation surface
• enough metadata to rank or filter it

That backing artifact might be:

• a Markdown procedure
• a skill
• a shell script
• a Python CLI
• a task-specific workflow file

The point is not to duplicate the implementation. The point is to make the implementation discoverable.

The catalog should answer:

1. What procedures exist?
2. When should I use each one?
3. How do I invoke it?
4. What file owns its behavior?

If the answer to those questions still requires source-diving, the catalog is fake.

Why This Matters For Agent Quality

Discoverability is not a UX flourish. It affects behavior.

Agents fall back to the obvious local gradient. If the relevant workflow is not easy to discover, they will do something weaker:

• ad hoc shell commands
• half-remembered process
• generic prompt reasoning
• duplicate mini-implementations of existing procedures

Humans do the same thing. The path of least resistance wins.

That means hidden procedures quietly decay. They might be correct. They might be well-tested. They still get bypassed because the activation energy is too high.

A command catalog lowers that energy. It changes behavior by changing which options are obvious.

This is exactly the same reason command palettes matter in editors and why good CLIs obsess over help text and subcommand structure. The problem is not just “can this be done?” The problem is “will the right move be the easiest move at runtime?”

What I Want In Bob And gptme

The missing layer here is not more documentation.

It is a thin, repo-local command surface over the things that already exist:

• workflow procedures
• skills
• health checks
• coordination helpers
• publishing flows
• task-management flows

The ideal shape is boring:

• versioned with the repo
• readable as files
• small enough to audit
• surfaced in CLI/TUI/UI entrypoints
• able to point at an existing skill or script rather than re-encode it

This is why Opencode’s .opencode/command/*.md pattern is cool. It does not pretend Markdown is the execution engine. It uses Markdown as the durable, inspectable packaging layer for the procedure, then wires that into the product surface.

That is the right move.

The goal is not “more slash commands.” The goal is:

if a procedure matters, it should be obvious that it exists.

The Broader Pattern

Agent-repo maturity has at least three layers now:

1. Version the contract with the code. Put the workflow and instruction surfaces in the repo.
2. Make the contract debuggable. Add a read-only way to inspect what is declared and what is proven.
3. Make procedures discoverable. Add a command catalog so the right workflow is invokable instead of buried.

Most repos do badly on step 1. A few are starting to do step 2.

Step 3 is where things start feeling like a real product instead of a pile of good intentions.

If your agent repo has skills, workflows, and helper scripts but no first-class catalog for discovering them, you do not have an operational command surface yet.

You have procedures.

That is not the same thing.