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"]
```
engrt capability validate github/repo-health
engrt 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.

engrt 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 $ENGRT_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

Runtime ships no capability examples. Use the self-contained quick-start fixture, or an external corpus you have access to. Author into your selected source, not into Runtime Home:

engrt capability list

The authoring contract ships as ordinary files in Runtime Home. Open them in your editor — the File Engine will refuse engrt 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:

engrt 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 engrt <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 (engrt capability list)
  3. Author Markdown into that source, never silently into Runtime Home
  4. engrt capability validate — the runtime is the compiler. A pass proves grammar and this binary's operations, not source admission or permission to run
  5. engrt github file put — the provider encodes content; do not use github api PUT …/contents/…, git, gh, or curl
  6. Verify with engrt 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 — engrt capability validate lets you inspect the whole workflow without touching anything.

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