Capability descriptions as routing contracts

You do not need to know the Capability name

People usually say “comment on this Jira issue” or “turn this research into a cited brief,” not “run Capability X.” A good description connects that natural request to the right tool.

A Capability is a reusable unit for handling a particular kind of request. Its description is the short explanation that tells an agent when to select it. A vague description forces users to memorize product names and agents to guess between similar tools. A precise one lets users focus on outcomes and gives authors a testable way to correct wrong selections.

Compare these examples.

Before

Fast, powerful automation for document work.

After

Use this when turning an internal specification into draft release notes.
It can read the specification and produce a draft in the required format.
Use docs-search when the request is only to find an existing document.
After editorial approval, hand publication to release-publisher.

The second version is less promotional and much more useful. It tells a person whether their request fits, and it gives the agent criteria for selection, rejection, and handoff. That makes the description a routing contract, an agreed rule for sending a request to the right Capability.

Four lines reveal selection, scope, boundary, and handoff

WHEN: when should it be selected?

Describe the user’s intended outcome, target, and any condition that changes the choice.

• Prefer “use when finding and editing an existing Confluence page” to “use for document work.”
• Prefer “use when generating, editing, or comparing a standalone image” to “image tool.”

CAN: what can it actually do?

Use concrete verbs only for implemented and verified operations. The action surface is the set of commands or API operations the Capability actually exposes.

• Prefer “read, create, update, and comment on Jira issues” to “manage Atlassian.”
• Do not promise deletion or deployment if no verified action supports it.

Describing a risky write action does not authorize it. The description states the supported scope; runtime approval and safety controls govern the actual execution.

BOUNDARY: when should another Capability be selected?

Name the closest alternative and the real decision point. “Do not use for unrelated work” helps nobody.

Use GitHub, not this Capability, for repository issues, pull requests, or Actions runs.

COMPOSITION: what joins the next step?

Composition means combining Capabilities into one workflow. Do not merely list adjacent tools; state when and what is handed off.

Combine with Verified Research when turning evidence from Jira and Confluence into a cited brief.

If there is no follow-up, say where this Capability finishes instead of inventing a composition.

flowchart TD
  A[Confirm real support] --> B[Collect user requests]
  B --> C[Write WHEN, CAN, BOUNDARY]
  C --> D[Test conflicts with neighbors]
  D --> E{Every verb verified?}
  E -->|No| C
  E -->|Yes| F[Sync surfaces and run fresh-agent test]

A five-step writing method

1. Inspect the real contract first

Before drafting, inspect the actual commands, inputs and outputs, read and write scope, authentication and recovery flow, and verified success and failure paths. Inspect the nearest neighboring Capability too. The goal is not to list what seems possible, but what can be demonstrated now.

2. Collect realistic user requests

Write at least three requests that must select the Capability, two similar requests that must not, one likely conflict with a neighbor, and one composite request. Starting with phrases people would actually use keeps the description from drifting into API names and internal architecture.

3. Draft four lines

WHEN: [Use for this intent, target, and condition.]
CAN: [Perform these verified actions.]
BOUNDARY: [Use this neighboring Capability under this condition.]
COMPOSITION: [For this next outcome, combine with or hand off to this Capability.]

Find gaps and conflicts before polishing the prose.

4. Rewrite in the user’s language

Implementation terms such as OAuth, MCP, gateway digests, or REST versions rarely help a user choose. Unless a term changes selection, move it to the Skill body, Harness specification, onboarding, or safety procedure.

Implementation-centered	User-centered
Supports issue.transition	Can change a Jira issue’s status.
Runs an image job through a provider SDK	Can generate and verify a standalone image.
Produces a citation bundle	Cross-checks public sources and returns citable evidence.

5. Match every verb to the action surface

Description verb	Real action	Success checked	Failure or permission checked	Decision
Create	issue.create	Yes	Yes	Keep
Update	issue.update	Yes	Yes	Keep
Delete	None	No	No	Remove

An unsupported verb must either be implemented and verified or removed.

AgentSkill and CLI Harness must mean the same thing

An AgentSkill guides an agent’s judgment, procedure, and command choice. A CLI Harness performs controlled software operations and returns structured results. They can play different roles while representing one Capability, so their selection meaning must not diverge.

• Keep the canonical name and user-facing title aligned.
• Preserve the meaning of WHEN, CAN, BOUNDARY, and COMPOSITION.
• Let the Skill describe judgment and procedure, and the Harness describe execution and verification.
• If both surfaces share one description field, require exact string equality.
• If fields differ, neither may imply a different scope or boundary.

Test descriptions as selection experiments

Run at least these checks:

1. Positive triggers: does it win for three representative requests?
2. Near-negative triggers: is it rejected for at least two close alternatives?
3. Neighbor conflict: does it avoid claiming the same request as its nearest neighbor?
4. Composition: does a composite request connect the right Capabilities in the right order?
5. Supported scope: does every description verb map to a verified action?

When a test fails, do not rewrite the request to force a pass. Narrow WHEN, make BOUNDARY name the real fork, or remove an exaggerated CAN verb.

A canonical description is the source that all copies must follow. Check every surface that actually exists in the project: Registry metadata, canonical and installed Skill frontmatter, Harness metadata, and the catalog injected into an agent’s context. Drift occurs when these copies disagree.

Finally, run a fresh-agent test: give only the description to an agent with no project conversation or author commentary. It should choose correctly for representative requests, reject close alternatives, compose with neighbors, and avoid expecting unsupported work. If the author must explain it, the contract is not self-contained.

Patterns to avoid

Pattern	Example	Why it fails
Capability boasting	“A powerful enterprise integration.”	No selection condition.
Implementation inventory	“Uses OAuth, MCP, and REST v3.”	Internals replace user intent.
Unlimited scope	“Manages every workspace operation.”	Implies unsupported actions.
Missing boundary	“For documents and collaboration.”	Does not identify the service or alternative.
Vague negative	“Not for unsupported work.”	Gives no decision rule.
Local organizational shorthand	“Use when Forge deploys our Capability.”	New users and agents lack the context.

Review checklist

• The first sentence states user intent, target, and condition.
• New technical terms are defined in plain language.
• Supported and unsupported work are separated without exaggeration.
• The nearest alternative and real decision point are named.
• Every CAN verb exists on the verified action surface.
• Positive, negative, neighbor, and composition tests pass.
• Registry, Skill, Harness, installed, and injected copies that exist are synchronized.
• A fresh agent can reproduce selection and rejection from the description alone.
• Tests were rerun against the final text.

Copyable template

Use this when [the user’s desired outcome, target, and important condition].
It can [perform these verified core actions].
Use [neighboring Capability] when [the nearest alternative condition applies].
For [follow-up outcome], combine with [companion Capability] and hand off [result].

If no composition is needed, replace the last line with “It completes this scope on its own.” A good description does not advertise everything. It lets people state the result they want, and lets an agent choose, stop, and hand off correctly from those words alone.