Sharing a Capability Source

A capability repository or catalog owns the definitions. Configure it under capabilities.sources so Runtime reports which source won and the digest of the exact bytes it resolved. Runtime Home remains a non-authoritative cache, not an authoring database.

Team setup

Clone the source at a reviewed revision and record the commit:

git clone https://github.com/engineeringruntime/engineering-runtime-capabilities.git \
  ~/work/engineering-runtime-capabilities
git -C ~/work/engineering-runtime-capabilities checkout <reviewed-commit>
git -C ~/work/engineering-runtime-capabilities rev-parse HEAD

Create a user-owned config file outside Runtime Home:

schema_version: 2

capabilities:
  authoring_source: team-worktree
  sources:
    - name: team-worktree
      dir: /absolute/path/to/engineering-runtime-capabilities/capabilities

Select it and inspect the resolved inventory:

export RUNTIME_CONFIG_FILE=~/.config/engineering-runtime/config.yaml
runtime capability list
runtime --output json capability authoring-context
runtime capability validate files/notes-roundtrip

Text and JSON output carry the winning source, path and content digest. The source name should include the revision your clone is pinned to; Runtime 0.6.0 does not fetch or resolve a Git branch for you.

Everyone on the team can then run a capability by name from any working directory:

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

RUNTIME_CAPABILITIES_DIR names one authoritative directory

Since Runtime 0.9.2, RUNTIME_CAPABILITIES_DIR names one ordinary authoritative source, reported as capabilities-dir. It is the simplest setup when the team uses one checkout for both reading and authoring capabilities.

export RUNTIME_CAPABILITIES_DIR=/tmp/runtime-capabilities
runtime capability list

Runtime never fetches or seeds definitions into the selected directory; clone or create it first. With the variable unset, the fallback <Runtime Home>/capabilities/ cache is non-authoritative and searched last.

Authors

Continue when authoring-context reports authoring_ready: true, then write the file into the directory it names, using your own editor or agent. Since 0.9.2 neither an authoring_source selection nor a file_policy.write_roots grant is required for a single configured directory — name a source only when several compete.

Validate, then plan with representative inputs. Publish only after a separate explicit request:

runtime capability validate \
  ~/work/engineering-runtime-capabilities/capabilities/github/repo-health.md
runtime capability plan \
  ~/work/engineering-runtime-capabilities/capabilities/github/repo-health.md \
  --input repository=cli/cli

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

Do not base64 the file or call github api PUT …/contents/…. Reviewing a change is a pull request. Consumers update to a reviewed commit deliberately; they do not silently follow whatever a branch points at.

Path vs name

Form	Resolution
capability execute ./path/to/file.md	An existing file path is used exactly as given
capability execute github/repo-health	Ordered capabilities.sources first, then the implicit cache; first match wins

runtime capability list reports shadowed definitions rather than hiding them. That output is the check for which file will run.

CI

Check out the source at a tag or SHA, then select a config file that names its directory. A path relative to the job working directory is valid:

- name: Checkout capability source
  uses: actions/checkout@v4
  with:
    repository: engineeringruntime/engineering-runtime-capabilities
    ref: <reviewed-tag-or-sha>
    path: engineering-runtime-capabilities

- name: Validate and execute
  env:
    RUNTIME_CONFIG_FILE: ${{ github.workspace }}/runtime-config.yaml
  run: |
    runtime capability list
    runtime capability validate files/notes-roundtrip
    runtime capability execute files/notes-roundtrip \
      --input path=./notes.txt --input message=hello

runtime-config.yaml in the consuming repository:

schema_version: 2
capabilities:
  sources:
    - name: company-capabilities@<reviewed-tag-or-sha>
      dir: ./engineering-runtime-capabilities/capabilities

Validate everything on upgrade

After a Runtime upgrade, validate every file in the source against the new provider surface:

find ~/work/engineering-runtime-capabilities/capabilities -name '*.md' -print0 |
  while IFS= read -r -d '' f; do
    runtime capability validate "$f" >/dev/null || echo "FAILED: $f"
  done

What this is not

There is no capability registry API in Runtime 0.6.0: no runtime capability install, publish, version resolution or search. Distribution puts an exact directory on disk; capabilities.sources declares which directory is authoritative; Runtime validates and executes the resolved bytes.

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