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
<Runtime Home>/capabilities/ Seeded examples, yours to edit. Never overwritten by an upgrade
$RUNTIME_CAPABILITIES_DIR A shared, version-controlled directory for a team or CI fleet
Any path capability execute ./anywhere.md works from a file path

The shipped examples are the fastest way in:

ls ~/.engineering-runtime/capabilities/files/     # auth-free — run these first
ls ~/.engineering-runtime/capabilities/github/    # needs RUNTIME_GITHUB_TOKEN

cat ~/.engineering-runtime/capabilities/files/notes-roundtrip.md

The authoring contract ships too, as real files rather than hidden prompts:

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

The company library

A larger, curated set lives in engineering-runtime-capabilities — point RUNTIME_CAPABILITIES_DIR at a clone and execute by name:

export RUNTIME_CAPABILITIES_DIR=~/work/engineering-runtime-capabilities/capabilities
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. An AI (or a human) discovers what is possible from --help, the Runtime Home's commands/ cheatsheets and specs/
  2. Authors a capability naming only published operations
  3. runtime capability validate — the runtime is the compiler
  4. runtime capability execute — the same deterministic path forever after

A capability that doesn't validate doesn't run, 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.