Skip to content

Capabilities Overview

An Engineering Capability is a Markdown file describing a reusable engineering workflow. Any human or AI can author one; the runtime executes it identically for everybody.

The runtime never executes the Markdown — only the fenced ```runtime block inside it. Everything else in the file exists for humans and AI to read, and has no effect on execution.

# Repository health check

Three reads that together answer "is this repo in good shape?"

```runtime
version: v1

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

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

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

runtime capability validate github/repo-health
runtime capability execute github/repo-health --input repository=cli/cli

Why a capability rather than a script

A shell script A capability
Calls tools directly Every step goes through policy, auth and audit
Pins the exact CLI it was written against Names operations; the provider owns the transport
Fails halfway through, discovered at runtime validate resolves every step against the real binary before anything runs
Behaves differently for a human, CI and an AI Identical for all three

The key property: a capability names what it wants, never how to get it. repo list may go out over REST today and GraphQL tomorrow; the operation name is the stable contract.

The three things to know

1. Only operations that exist

Every provider step is resolved against the provider's real operation surface at validation time. A capability naming an operation this runtime version does not have fails validation rather than mid-execution.

runtime github --help      # the authority on what exists

There is no "propose a new operation" escape hatch. If the runtime can't run it today, a capability can't ask it to.

2. Never a transport

transport: is not a key, and the parser will not let you pretend otherwise. If you find yourself needing a specific wire protocol, that is a signal the provider is missing an operation — add the operation, don't work around it.

3. No special powers

Each step dispatches through the same Bootstrap → Context → Policy → Auth → Execution → Audit lifecycle as any other command. A capability contributes no execution logic of its own — which is exactly why it is safe to let an AI write one.

Where capabilities live

Location Purpose
selected_source.dir — either $RUNTIME_CAPABILITIES_DIR or a configured capabilities.sources directory The authoritative directory where you read and author capabilities
<Runtime Home>/capabilities/ when no external directory is selected Unset fallback compatibility cache; non-authoritative and not where shared source trust is established
Any path capability execute ./anywhere.md works from a file path

The shipped examples are the fastest way to see the shape. Author into your source, not into Runtime Home:

runtime capability list

The authoring contract ships as ordinary files in Runtime Home. Open them in your editor — the File Engine will refuse runtime files read of Runtime-owned contracts:

<Runtime Home>/RUNTIME-AGENT.md
<Runtime Home>/manifest.json
<Runtime Home>/specs/capability-spec.md
<Runtime Home>/specs/github/capability-spec-github.md
<Runtime Home>/specs/files/capability-spec-files.md

The company library

A larger, curated set lives in engineering-runtime-capabilities. Clone it at a reviewed revision, declare its capabilities/ directory under capabilities.sources, then execute by name:

runtime capability execute files/notes-roundtrip --input path=./n.txt --input message=hi

See Sharing a Capability Directory.

AI authors, the runtime compiles

The intended workflow, and the reason the format is what it is:

  1. Discover locally from <Runtime Home>/RUNTIME-AGENT.md, manifest.json, specs/, and runtime <provider> --help. If those contracts are missing, restore them from this binary and stop — do not fetch /metadata/*.
  2. Learn the shape from the configured capability source (runtime capability list)
  3. Author Markdown into that source, never silently into Runtime Home
  4. runtime capability validate — the runtime is the compiler. A pass proves grammar and this binary's operations, not source admission or permission to run
  5. runtime github file put — the provider encodes content; do not use github api PUT …/contents/…, git, gh, or curl
  6. Verify with runtime audit tail. Execute only when the user asked to run it

A capability that doesn't validate doesn't get pushed, no matter how well-reasoned it looks. Humans and CI then re-run it with zero further AI involvement.

Next

Writing your first one? Start with Create a Capability — the whole arc in order, from a repetitive task to a validated, shared workflow.

See a real one

Showcase: scaffold and ship a Java service — 18 steps across two providers and the Command Engine, ending in a triggered CI run. It shows what a capability is for, rather than just how one is shaped.

It needs a write-scoped token and the public capability store, so it is a showcase rather than a first run — runtime capability validate lets you inspect the whole workflow without touching anything.

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