Create a Capability¶

The whole arc, in order: from "I keep running these same commands" to a validated, audited, shared capability your team and CI can re-run forever.

Follow this page start to finish once. After that, the Authoring Reference is the page you'll come back to.

Working example used throughout

A repository health check — the summary, community profile and open PRs for one repo. Substitute your own task; the sequence doesn't change.

Before you start¶

runtime version
runtime config validate
runtime --output json capability authoring-context

config validate should show the expected compiled or selected config/policy. GitHub work also needs a working GitHub auth provider; the auth-free files path does not.

Continue when authoring_ready is true. It proves Runtime knows which single directory your file belongs in and that a capability document can actually be created there. If it is false, the reason names the fix — Troubleshooting.

If you have no capabilities directory yet

Two commands, and nothing else to configure:

git clone https://github.com/engineeringruntime/engineering-runtime-capabilities
export RUNTIME_CAPABILITIES_DIR=$PWD/engineering-runtime-capabilities/capabilities

That gives you working examples to read and a place to write. Since 0.9.2 the same directory serves both — there is no separate authoring setting to configure first.

Or ask your AI assistant to do all of this

Everything below can be driven by an assistant, because the contract it needs ships with the binary. The full prompt is in the Prompt Library; the short version:

Before writing anything, run `runtime --output json capability
authoring-context` and use its `runtime_home` and contract paths — then read
RUNTIME-AGENT.md, capability-spec.md and the spec for the provider I need. Then write me a capability that <outcome>,
put it where authoring-context says, and validate → plan → execute it.

authoring-context goes first because it answers the two things an assistant otherwise guesses: where the file belongs, and what policy will allow.

Step 1 — Write down the outcome, not the commands¶

Start from what you want to be true when it finishes, in one sentence:

"For a given repository, show me its summary, whether it has a README and licence, and what PRs are open."

This matters because a capability names operations, not a script's steps. If you can't say the outcome in a sentence, you probably have two capabilities.

Step 2 — Find the operations that serve it¶

Never guess at operation names. Every provider publishes its real surface:

runtime github --help      # every operation, and the transport chosen for it
runtime files --help

For task-shaped starting points, the Runtime Home ships a use-case reference organized by what engineers are trying to achieve:

cat ~/.engineering-runtime/commands/github_commands.txt

For our example, three operations look right: repo summary, api GET for the community profile, and pr list.

The transport column is information, not a choice

--help shows rest, graphql, cli or file per operation. You never select one, and nothing you write should depend on it.

Step 3 — Prove each operation before you write anything¶

This is the step that saves the most time, and the one most people skip. Writing nine steps and discovering step two never worked is the default failure mode.

First check the command line resolves — no auth, no policy, no execution, no network:

runtime resolve github repo summary cli/cli
runtime resolve github api GET /repos/cli/cli/community/profile
runtime resolve github pr list --repo cli/cli

Then run each one for real, once, to see the shape of what comes back:

runtime github repo summary cli/cli
runtime github api GET /repos/cli/cli/community/profile
runtime github pr list --repo cli/cli --limit 5

If an operation fails here, it will fail inside a capability too — a capability gets no special powers.

Step 4 — Decide what is an input¶

The rule of thumb:

The value is…	Where it belongs
what this run is about — a repo, a ticket, a version	An `input`
where the operation should land — org, project, namespace	An explicit input, or the native tool's context when that operation has a binding adapter

Never hardcode an org, repository or environment into args. In our example, the repository is clearly the subject of the run, so it becomes an input.

Step 5 — Write the file into the selected source¶

Create repo-health-check.md under the selected_source.dir reported by authoring-context, using your editor or agent's ordinary file tools. Authoring is you editing source, not Runtime acting for an operator, so it does not go through the File Engine or require file_policy.write_roots. Give the file the reviewed Markdown below and inspect the resulting diff:

# Repository health check

Summary, community profile and open PRs for one repository.

```runtime
version: v1

inputs:
  repository:
    description: Repository to inspect, as <owner>/<repo>
    required: true

workflow:
  - provider: github
    args: [repo, summary, "${repository}"]

  - provider: github
    args: [api, GET, "/repos/${repository}/community/profile"]

  - provider: github
    args: [pr, list, --repo, "${repository}", --limit, "10"]
```

Three things that trip people up:

The prose is for humans. Only the fenced ```runtime block executes.
args are the CLI words, split into a list. runtime github repo summary cli/cli becomes args: [repo, summary, "${repository}"].
Exactly one of provider: or binary: per step. Never both, never neither.

Prefer required: true on every input. An input you declare but don't supply stays in the arguments as the literal string ${name}.

Step 6 — Validate¶

runtime capability validate ./repo-health-check.md

Validation resolves every step against the operation surface of the binary you are running, and reports every problem it finds — not just the first. A typo, a renamed operation or a binary missing from allowed_binaries fails here, before anything executes.

Fix and re-run until clean. A capability that doesn't validate doesn't run, no matter how reasonable it looks.

Step 7 — Plan without executing¶

runtime capability plan ./repo-health-check.md --input repository=cli/cli

Planning substitutes the real inputs and evaluates context, file grants, the compiled safety floor and declarative policy for every step. It authenticates nothing, runs no command, contacts no network, changes no file, and writes no audit record. Fix every denial and re-run until clean.

Review the selected source, file diff, digest and plan together. A successful plan is evidence for this review; it is not permission to execute or publish.

Step 8 — Execute only when separately requested¶

runtime capability execute ./repo-health-check.md --input repository=cli/cli

Machine-readable, covering every step:

runtime --output json capability execute ./repo-health-check.md --input repository=cli/cli

Execution re-validates, checks required inputs, substitutes ${name}, then runs each step in order — stopping at the first failure. Steps before it have already run. Capabilities are not transactional, so put anything destructive or expensive last.

Step 9 — Confirm what actually happened¶

runtime audit tail -n 5 --output json

One record per step, each carrying the transport its provider chose. In our example that's graphql for the summary and rest for the profile — and you named neither. That is the property that keeps the file working when a provider changes how it reaches the platform.

A capability on one laptop is a script. Move it into a version-controlled directory and it becomes something a team and CI both run:

cp ./repo-health-check.md \
   ~/work/engineering-runtime-capabilities/capabilities/github/

runtime capability validate \
  ~/work/engineering-runtime-capabilities/capabilities/github/repo-health-check.md

Commit it and open a pull request — the format is Markdown precisely so the review is a readable diff. From an installed Runtime, the governed push is:

runtime github file put owner/repo capabilities/github/repo-health-check.md \
  message="Add repo-health-check" \
  content="$(cat ~/work/engineering-runtime-capabilities/capabilities/github/repo-health-check.md)"

Do not base64 the file or call github api PUT …/contents/…. From then on, consumers pin the accepted revision and configure it under capabilities.sources; CI executes the same file with no model in the loop.

Full setup: Sharing a Capability Source and CI/CD.

When something goes wrong¶

Symptom	Where to look
`args don't resolve to an operation`	`runtime <provider> --help` — it may not exist in your version
An unrecognized key, with a line number	Only these keys are valid
`binary not allowed`	Your `policy-config.yaml` may predate the release that added it — Policy
Validated fine, denied by `plan`	Policy denies those specific substituted arguments; review the reported steps
`plan` reports a missing input	Supply the required `--input key=value`; never invent it
Works by path, fails by name	`runtime capability list` — check the configured source, winning definition and digest
`authoring_ready` is false	Read its exact reason; check `authoring_source`, the absolute source path, directory existence and OS write permissions

More: Validate & Execute and Troubleshooting.

Go deeper¶


Every key, rule and limitation	Authoring Reference
The validate/execute loop in detail	Validate & Execute
Command flags and addressing	`runtime capability`
Team and CI distribution	Sharing a Capability Source
Working files to copy	Examples

The authoring contract also ships inside your Runtime Home, refreshed with every binary version:

cat ~/.engineering-runtime/specs/capability-spec.md
cat ~/.engineering-runtime/specs/github/capability-spec-github.md
cat ~/.engineering-runtime/specs/files/capability-spec-files.md

Operational examples on this site were verified against Runtime 0.9.8. After bootstrap, the version-exact files in Runtime Home win.