> ## Documentation Index
> Fetch the complete documentation index at: https://docs.doppels.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Capabilities: The Public Contract for Your Automation

> A Capability declares what an automation does — its inputs and outputs — as a versioned YAML manifest you commit to your repository.

A Capability is a versioned declaration of what an automation does. It answers one question: given these inputs, what outputs will be produced? It says nothing about how those outputs are produced — that responsibility belongs to a Recipe. This separation lets the same Capability be fulfilled by multiple Recipes (different implementations for different environments), or fulfilled by a human operator when no automated Recipe exists yet.

## What a Capability defines

A Capability manifest contains exactly three things:

* **Identity** — a machine-readable name, a semantic version, and a human-readable display name.
* **Inputs** — the typed parameters a caller must supply before the Capability can run.
* **Outputs** — the typed values or artifacts the Capability guarantees to return on success.

The Capability does not contain shell commands, file paths, approval rules, or any reference to how the work gets done. That strict boundary is what makes Capabilities shareable, reviewable, and stable across Recipe changes.

## A Capability without a Recipe

A Capability can exist before any Recipe is written for it. When you run `doppels run capability/<name>` against a Capability that has no Recipe, the CLI treats the run as a manual fulfillment — a human delivers the declared outputs. This is intentional: you can publish the contract first, agree on inputs and outputs with your team, and implement the automation later.

## Example

```yaml theme={null}
apiVersion: doppels.so/v1alpha1
kind: Capability

metadata:
  name: release-build
  version: 1.0.0
  displayName: Generate Release

inputs:
  version:
    type: string
    required: true

outputs:
  archive:
    type: artifact
    mediaType: application/gzip
  checksum:
    type: string
```

This Capability declares one required string input (`version`) and two outputs: a gzip artifact (`archive`) and a string (`checksum`). Any Recipe that `provides: [release-build]` must satisfy both outputs.

## Field reference

<ParamField path="apiVersion" type="string" required>
  Always `doppels.so/v1alpha1`. Identifies the schema version used to validate this manifest.
</ParamField>

<ParamField path="kind" type="string" required>
  Always `Capability`. Tells the CLI and validator which schema to apply.
</ParamField>

<ParamField path="metadata.name" type="string" required>
  The machine-readable identifier for this Capability. Used in `doppels run capability/<name>`, in Recipe `provides` lists, and in expressions. Use lowercase kebab-case (e.g. `release-build`).
</ParamField>

<ParamField path="metadata.version" type="string" required>
  A semantic version string (e.g. `1.0.0`). Capability versions are immutable once published — changing inputs or outputs requires a new version.
</ParamField>

<ParamField path="metadata.displayName" type="string">
  A human-readable label shown in `doppels describe` output and any UI surfaces. Spaces and mixed case are allowed.
</ParamField>

<ParamField path="inputs.<name>.type" type="string">
  The type of this input parameter. Accepted values: `string`, `integer`, `number`, `boolean`, `artifact`.
</ParamField>

<ParamField path="inputs.<name>.required" type="boolean">
  When `true`, the CLI rejects a run attempt if this input is not supplied. Defaults to `false` when omitted.
</ParamField>

<ParamField path="outputs.<name>.type" type="string">
  The type of this output value. Accepted values mirror input types: `string`, `integer`, `number`, `boolean`, `artifact`.
</ParamField>

<ParamField path="outputs.<name>.mediaType" type="string">
  The MIME type of an `artifact` output (e.g. `application/gzip`, `text/csv`). Only meaningful when `type` is `artifact`.
</ParamField>

## All declared outputs are required

Every output you declare in a Capability must be present in the result when the Capability runs. If a Recipe's `returns` block omits a declared output, `doppels validate` reports an error. This contract is enforced at validation time so you catch gaps before they reach a production run.

## Where to store Capability manifests

Place Capability manifests in the `capabilities/` directory at the root of your project:

```text theme={null}
your-project/
  capabilities/
    release-build.yaml
    greet.yaml
```

The CLI discovers Capabilities by scanning this directory. File names do not need to match `metadata.name`, but keeping them consistent makes the project easier to navigate.

## Listing your Capabilities

Run the following command from any directory within your project to see all locally discovered Capabilities:

```shell theme={null}
doppels capabilities list
```

To inspect a specific Capability's full contract:

```shell theme={null}
doppels describe capability/release-build
```

***

<CardGroup cols={2}>
  <Card title="Recipes" icon="scroll" href="/concepts/recipes">
    Learn how Recipes implement Capabilities with shell steps and output mappings.
  </Card>

  <Card title="How It Works" icon="diagram-project" href="/concepts/how-it-works">
    See how Capabilities fit into the full Doppels execution model.
  </Card>
</CardGroup>