Sharing a Capability Directory

RUNTIME_CAPABILITIES_DIR relocates the capabilities directory out of the Runtime Home entirely, so a team or a CI fleet can point every machine at one shared, version-controlled directory.

export RUNTIME_CAPABILITIES_DIR=~/work/team-capabilities
runtime bootstrap
runtime capability execute github/repo-health --input repository=cli/cli

Why it is a separate variable

The directory is both where examples are seeded and where capability names are resolved. Making it independent of ENGINEERING_RUNTIME_HOME means you can share engineering knowledge without relocating runtime state — logs, cache, config and policy stay per-machine, where they belong.

When the override is set, no capabilities/ directory is created inside the Runtime Home at all.

Team setup

git clone https://github.com/kishore-gutta/engineering-runtime-capabilities.git \
  ~/work/engineering-runtime-capabilities

# add to ~/.zshrc or ~/.bashrc
export RUNTIME_CAPABILITIES_DIR=~/work/engineering-runtime-capabilities/capabilities

runtime config validate      # confirms the path the runtime resolved
runtime capability validate files/notes-roundtrip

Everyone on the team then runs capabilities by name, from any working directory:

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

Updating the library is git pull. Reviewing a change is a pull request.

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	Resolved inside the capabilities directory, with and without .md

Both work regardless of the override. Name resolution is the one that benefits from a shared directory — it is what makes a capability portable across machines and pipelines.

CI

Clone the library, point at it, execute by name:

- name: Clone capability registry
  uses: actions/checkout@v4
  with:
    repository: kishore-gutta/engineering-runtime-capabilities
    path: capabilities-registry

- name: Execute
  env:
    RUNTIME_CAPABILITIES_DIR: ${{ github.workspace }}/capabilities-registry/capabilities
  run: |
    runtime capability validate github/repo-health
    runtime capability execute github/repo-health --input repository=cli/cli

CI always clones the latest library, so a capability improved in the registry is picked up on the next run without touching the pipeline.

Never point RUNTIME_CAPABILITIES_DIR at a working tree during bootstrap

Bootstrap seeds example capabilities into whatever this variable points at. Aiming it at a repository you have checked out means the runtime writes its shipped examples into your working tree, and they show up as untracked changes.

In CI, clear the variable for the bootstrap step and set it only for execution:

- name: Bootstrap
  env:
    RUNTIME_CAPABILITIES_DIR: ""
  run: runtime bootstrap

The shared setup-runtime action already does this.

Validate everything on upgrade

A shared library is validated against whichever binary a given machine has installed. After a runtime upgrade, re-validate the whole directory:

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

Running this as a scheduled CI job against the registry catches drift between the library and the release before an engineer does.

What this is not

There is no capability registry API — no runtime capability install, no publish, no version resolution, no search. A capability's storage location is the author's problem, not the runtime's, and RUNTIME_CAPABILITIES_DIR plus git is the whole distribution mechanism today.

Packaged, versioned capability distribution is a known future direction. It does not exist yet, so don't design around it.