Capabilities
The unit that makes the Runtime worth having¶
Without capabilities, Engineering Runtime is a governed command line. With them it becomes the place your organisation's engineering knowledge lives and executes — reviewed, versioned, and identical whoever runs it.
From nothing to a running capability
Three commands¶
# 1 — get the library. 107 working capabilities to read, and a place to write.
$ git clone https://github.com/engineeringruntime/engineering-runtime-capabilities
$ export RUNTIME_CAPABILITIES_DIR=$PWD/engineering-runtime-capabilities/capabilities
# 2 — confirm you can author. Nothing to configure first.
$ runtime capability authoring-context
Authoring ready: true
Authoring source: capabilities-dir — …/capabilities
# 3 — run one. No credential needed for the File Engine.
$ runtime capability execute files/notes-roundtrip --input path=notes.txt --input message='first capability'
Step 1: files write transport: file wrote 16 bytes to notes.txt
Step 2: files read transport: file read 16 bytes from notes.txt
first capability
capability completed: 2 step(s)
A capability can also express one estate-wide, reviewable local change without inventing a migration language:
runtime capability execute files/estate-config-update \
--input root=./checked-out-repositories \
--input old_branch=master --input new_branch=main \
--input owner=@platform --dry-run
# Review the file table, exact counts and bounded diffs; then apply locally.
runtime capability execute files/estate-config-update \
--input root=./checked-out-repositories \
--input old_branch=master --input new_branch=main \
--input owner=@platform
Capability-wide preview checks every step before step one. File edits preview, read-only steps may execute, and a mutating operation with no registered preview contract refuses the whole workflow.
Add one GitHub token and the rest of the library opens:
# One variable covers REST, GraphQL and the gh CLI. Runtime hands the
# credential to each transport itself — `gh auth login` is not needed.
$ export RUNTIME_GITHUB_TOKEN=ghp_your_token
# REST — one step.
$ runtime capability execute github/repo-topics-review --input repository=cli/cli
Step 1: github api transport: rest GET /repos/cli/cli/topics -> 200
{ "names": [ "github-api-v4", "cli", "git", "golang" ] }
# …and one file can cross transports. This is three steps over two:
$ runtime capability execute github/github-repo-health --input repository=cli/cli
Step 1: github repo summary transport: graphql -> 200 46121 stars, 60 open PRs
Step 2: github pr list transport: cli gh pr list --repo cli/cli …
Step 3: github run list transport: cli gh run list --repo cli/cli …
capability completed: 3 step(s)
# …then write your own Markdown file in that directory, with any editor.
Or hand the whole thing to your AI assistant — everything it needs ships with the binary:
I want to author an Engineering Runtime capability for the release installed on
this machine. The outcome I want is:
show me the repositories that have forked cli/cli, newest first
If I have no capability library yet:
git clone https://github.com/engineeringruntime/engineering-runtime-capabilities
export RUNTIME_CAPABILITIES_DIR=$PWD/engineering-runtime-capabilities/capabilities
Run `runtime --output json capability authoring-context`. Treat its output as the
source of truth — use runtime_home, the absolute paths in contracts, and
selected_source.dir. Do not reconstruct a path from ~, and do not assume
$RUNTIME_CAPABILITIES_DIR is the selected source.
Check `runtime capability list` for one that already produces this outcome
before writing a new one.
Read the contract at the `agent` path and follow it exactly. It is written for
this exact release and wins over anything you already know, including this
prompt.
Validate, plan, then execute — pass `--output json` on every step, not just
authoring-context, so each result is one structured payload you can read
fields from instead of banner text you have to parse. Validate passing is not
evidence it works — show me what each step returned.
The prompt is short because it does not repeat the contract. It carries only what
an assistant needs before it can read one — the outcome, where to get a
library, and the command that reports every path. Everything else lives in
RUNTIME-AGENT.md, which is written into your Runtime Home and
refreshed on every version change, so an assistant reads the contract for
the binary you actually have — not the one it was trained on.
That is the point of shipping it: a new release teaches itself.
The sample outcome is real. Following this exact prompt on 0.9.3 produced
github/repo-forks-review,
which is now in the public library — validated, planned, then executed against
cli/cli for twenty forks.
One directory, read from and written to. No configuration file to edit before your first capability, and no policy grant to arrange — writing a capability is you editing a file. Runtime governs what it runs, not what you type. The token is the one credential you supply; Runtime validates it once and passes it to whichever transport a step needs, rather than inheriting whatever your shell happens to be logged into.
Why they are the core¶
Most engineering knowledge has no home.
It lives in a script on someone's laptop, a workflow file three repositories away, a wiki page last edited two years ago, a chat log, or the one engineer who remembers the order the steps go in. None of that can be reviewed as a unit, tested as a unit, or handed to somebody else as a unit.
A capability is that unit.
A capability is the point where "how we do this" stops being folklore and becomes something you can execute, review and improve.
Everything else in Engineering Runtime exists to make capabilities safe to run: policy decides whether they may, providers and engines carry out the work, audit records what happened. The capability is the part with the value in it.
What a team can achieve with them¶
These are shapes of problem, not a product list — the kind of work that stops being re-solved once it is captured once.
Standards that actually hold¶
Every repository checked against the same rules, on demand, by anyone — instead of a policy document nobody can enforce and an audit nobody wants to run.
A new service that starts right¶
Scaffolded, documented and wired up the same way every time, so the tenth service does not inherit the shortcuts taken on the first.
The routine work, done routinely¶
The report somebody assembles by hand each week, the log that needs rotating, the checklist before a release — captured once and run the same way after.
Knowledge that survives people¶
When the engineer who knew the sequence moves team, the sequence stays. It was never in their head; it was in a file, reviewed like any other change.
The same capability then runs from a terminal, a pipeline, or an AI assistant — without anyone rebuilding it for the new caller.
What one actually is¶
A capability is a file. That is the whole trick, and everything useful follows from it.
Written once Reviewed in a pull request Versioned in git Improved over time Run by human · CI · AI
It states what it needs, and the ordered operations that make up the work. Because it is a file, it gets everything files already have — history, diffs, review, blame, rollback — and none of that had to be invented for automation.
Runtime executes those operations through the surfaces it ships today: filesgithub providers, plus approved binaries through the Command Engine.
The exact format, inputs and execution rules live in the technical documentation — this page is about what they are for.
How to author a capability Run your first one
Why this scales¶
A capability is worth writing because it is worth reusing. Two things follow.
Without them
- Each caller builds its own version
- AI generates a fresh script every time
- Fixes land in one copy, not the others
- Knowledge leaves when people do
With them
- One implementation, every caller
- An agent finds what exists before writing new
- A fix improves it everywhere at once
- The knowledge outlives the author
It also keeps the Runtime small. New workflows do not become new built-in commands — they become capabilities. The number of useful operations can grow without the thing executing them growing with it.