Skip to content

Why Engineering Runtime capabilities are Markdown files with a runtime block

November 9, 2026 · Kishore Babu Gutta

Before an AI agent executes an engineering operation, it should know what it is about to do.

What is the purpose? Which credentials, permissions and tools are required? What inputs must it supply? Which commands should it use? What would a successful result mean?

We chose Markdown (.md) files with a fenced runtime block for Engineering Runtime (ENGRT) capabilities because those answers and the executable contract should be available together—before execution.

Markdown provides readable engineering knowledge. The runtime block provides a machine-validated workflow. These are two different responsibilities in one versioned file.

Why an agent needs the explanation first

Suppose an agent is asked to inspect a GitHub repository. The right starting point is not to improvise a REST request or shell script.

A good capability can explain:

  • Intent: It reads repository metadata, not changes the repository.
  • Prerequisites: It needs suitable GitHub authentication and target access; some other capabilities also require installed provider CLIs.
  • Inputs: The repository must be specified explicitly.
  • How to run: The exact commands to validate, plan and execute.
  • Scope: What the result includes, what it excludes, and when another capability is a better choice.

This knowledge lives in ordinary Markdown, where an engineer can read it and an AI assistant can inspect it. It does not have to be reconstructed from model memory or a past chat.

One file, two readers

File section Primary reader Responsibility
Markdown heading and prose Humans and AI agents Purpose, prerequisites, examples, rationale and limitations
Fenced runtime block Engineering Runtime Inputs, compatibility and declared provider/binary workflow

Runtime does not execute the prose. It parses and validates the recognized runtime block.

A Markdown sentence saying "requires authentication" helps an agent prepare; it does not authenticate anyone. An example command in prose is documentation, not an automatically executed step. A natural-language instruction cannot grant policy permission.

That separation is the key design choice: the file can be easy to understand without letting informal text become execution authority.

What the file looks like

The public library contains github/github-repo-view.md. It describes a single REST-backed GitHub repository metadata operation, its authentication prerequisite, its lack of dependency on gh, and its run commands.

Here is a shortened illustration based on that real capability:

# View a GitHub repository

Reads repository metadata. Requires GitHub authentication and
permission to view the target. No `gh` installation needed.

Run:
```sh
engrt capability validate capabilities/github/github-repo-view.md
engrt capability plan capabilities/github/github-repo-view.md \
  --input repository=cli/cli
engrt capability execute capabilities/github/github-repo-view.md \
  --input repository=cli/cli
```

```runtime
version: v1

inputs:
  repository:
    description: Repository to view, as owner/repo
    required: true

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

Everything above the fence helps a human or agent understand the operation. Inside the fence, the required repository input and GitHub provider step form a structured execution contract. The provider chooses its supported transport; the agent does not need to encode it in the capability.

The agent can select the capability and provide parameters. Runtime remains responsible for admitting and executing the requested operation.

Why Markdown instead of only YAML or JSON?

YAML and JSON are useful for structured machine input. But a complete engineering procedure needs more than fields: it needs context, examples, warnings, expected results and explanation of trade-offs.

Markdown works naturally in editors, pull requests and documentation systems. AI assistants commonly read and generate Markdown, making it a practical format for knowledge shared with humans. The small structured runtime fence retains a strictly checked grammar without requiring the whole document to become a bespoke programming language.

This is a design rationale, not a measured claim that every model understands Markdown better than every alternative, nor a guarantee that an agent will correctly follow text it reads.

Why the two layers belong together

A single Git-versioned .md file lets a team review both explanation and executable contract in the same pull request. The diff shows when inputs, provider operations or guidance change. It can be reused from a terminal, CI or an AI agent, and new agents can inspect it without needing the reasoning session that originally authored it.

The document can evolve with provider changes and Runtime compatibility requirements. Co-location does not automatically prevent documentation drift: authors still need to review examples and prerequisites against the actual supported operation.

The important boundary: prose is not a preflight gate

Prerequisites written in Markdown are readable guidance, not automatic enforcement.

Runtime enforces only the constraints its supported input validation, provider resolution, policy, compiled safety, authentication and context paths implement. validate checks the capability definition; plan helps inspect resolved work without dispatch. Neither proves that execution will succeed or that the final external state is correct.

Secrets should not be stored in capability Markdown. They belong in supported credential sources. Third-party capability text should be treated as untrusted until reviewed; even a valid runtime block is not proof of a safe or suitable operation.

Read first, execute second

Human or agent understands the goal
                ↓
Discover and read the capability .md
                ↓
Check purpose, prerequisites, inputs, limitations
                ↓
Validate and inspect the plan
                ↓
Request execution through ENGRT
                ↓
Evaluate results and available verification evidence

The agent must actually inspect the capability for the explanation to help. The installed Runtime also carries its version-matched authoring specification; that contract, not a model's training memory, determines supported syntax.

We did not choose Markdown because Markdown executes anything. We chose it because engineering knowledge should be readable before execution, while execution stays a separately validated contract.

Agents read the knowledge. Runtime executes the contract.

Further reading: Capabilities are executable contracts, not AI prompts, Self-authoring capabilities, and the public capability library.