# Resource YAML Creation

> Guidance for creating ado resource YAML files (discoveryspace, operation, actuatorconfiguration, samplestore, document). Covers metadata conventions, dynamic reference resolution with --use-latest/--with/--set, space design principles, avoiding duplicate resources, document reports, and validation. Use when creating or editing any ado resource YAML file.

- Skill: `ibm/resource-yaml-creation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ibm/resource-yaml-creation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ibm/resource-yaml-creation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: IBM (https://skillmd.com/u/ibm)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ibm/resource-yaml-creation

---


# Creating ado Resource YAML Files

For CLI command syntax, see [using-ado-cli](../using-ado-cli/SKILL.md). For full
problem formulation workflow, see
[define-experiment-campaign](../define-experiment-campaign/SKILL.md).

## Metadata Fields

Every resource YAML should include a `metadata` block. The CLI uses these for
display (`ado get --details`) and filtering (`ado get --label`,
`ado get --filter`).

```yaml
metadata:
  name: my_space # short human-readable identifier
  description: | # longer explanation of purpose
    Optimize learning rate and batch size for ResNet training.
  labels:
    project: my_project # arbitrary key=value pairs for filtering
    team: ml_team
```

- `name` and `description` are shown by `ado get --details`
- `labels` support filtering: `uv run ado get spaces --label project=my_project`
- `--filter` supports path-based filtering across any field:
  `uv run ado get spaces --filter 'config.metadata.name=my_space'`

### The `provisional` label

Set `provisional` at creation time when a space or operation is known **not**
to be meant for keeping long-term:

```yaml
metadata:
  labels:
    provisional: true
    provisonal_reason: testing
```

Use `provisional_reason` to record the reason with one of the following:

- `testing` — created to test some new functionality.
- `debug` — created to debug a problem.
- `temporary` — generic indicator that it's not meant to be kept.

## Dynamic Reference Resolution

Resource YAMLs often reference other resources by ID. Leave these as
placeholders and resolve them at creation time — do not hard-code IDs.

### --use-latest

Queries the current context's metastore to find the most recently created
resource of the given type.

```bash
# Create space, then operation that references it — no manual ID copy
uv run ado create space -f space.yaml
uv run ado create operation -f operation.yaml --use-latest space
```

### --with

Creates a dependency inline and injects its ID automatically.

```bash
# Create space + actuatorconfiguration + operation in one command
# Note: You cannot use --with store=store.yaml or store_id here
# The space must use default store or have a valid store_id in the YAML
uv run ado create operation -f operation.yaml \
  --with space=space.yaml \
  --with actuatorconfiguration=config.yaml
```

Note: Can also specify resources ids to --with

```bash
uv run ado create operation -f operation.yaml \
  --with space=space-abcd-1234
```

### --set

Overrides individual fields in the YAML at creation time without editing the
file. Useful for environment-specific values or quick one-off changes.

```bash
# Override the sample store identifier
uv run ado create space -f space.yaml --set sampleStoreIdentifier=my_store

# Override a nested field using dot notation
uv run ado create operation -f operation.yaml --set parameters.budget=100
```

`--set` takes `path=JSON_document` pairs and can be used multiple times.

## Validation

Always validate before creating:

```bash
uv run ado create RESOURCETYPE -f FILE --dry-run
```

`--dry-run` validates the YAML without creating the resource.

## Templates

Use `ado template` to generate a starter YAML for any resource type:

```bash
# Generic discoveryspace template
uv run ado template discoveryspace

# Space template pre-filled for a specific experiment
uv run ado template discoveryspace --from-experiment my_experiment

# Operation template for a specific operator
uv run ado template operation --operator-name ray_tune

# ActuatorConfiguration template for a specific actuator
uv run ado template actuatorconfiguration --actuator-identifier my_actuator
```

## Resource-Specific Guidance

### DiscoverySpace

See [define-experiment-campaign](../define-experiment-campaign/SKILL.md) for
further details on creating discovery spaces.

**Before creating** (ado create space), check if a matching space already
exists:

```bash
# Match by space config (entity space + experiments)
uv run ado get spaces --matching-space space.yaml

# Match by space ID
uv run ado get spaces --matching-space-id space-abc123

# Filter by label
uv run ado get spaces --label project=my_project --details
```

Reuse an existing space rather than creating a new one — it means the new
operation benefits from measurements already collected.

**Constitutive properties vs. parameterization**:

- Declare a property as a constitutive property domain in the entity space when
  you want to **explore a range of values** for that property.
- Use **experiment parameterization** when you want to change the default value
  of an optional experiment property but keep it fixed across all entities. Do
  not add a single-valued domain to the entity space just to override a default.

```yaml
# Correct: parameterization overrides experiment default, keeps it out of space
experiments:
  - actuatorIdentifier: trainer
    experimentIdentifier: train_model
    parameterization:
      - property:
          identifier: optimizer
        value: adam # overrides default "sgd"

# Incorrect: single-valued domain should be parameterization instead
entitySpace:
  - identifier: optimizer
    propertyDomain:
      variableType: DISCRETE_VARIABLE_TYPE
      values: [adam] # single value — use parameterization instead
```

**Creating a space with a fresh samplestore**:

```bash
uv run ado create space -f space.yaml --new-sample-store
```

### ActuatorConfiguration

**Before creating**, check if a compatible configuration already exists:

```bash
uv run ado get actuatorconfigurations --details
uv run ado get actuatorconfigurations --label actuator=my_actuator
```

Reuse an existing actuator configuration when appropriate rather than creating
duplicates.

### SampleStore

You rarely need to create a samplestore explicitly. Every project comes with a
`default` samplestore that is suitable for most use cases.

Create a new samplestore only when you explicitly want a clean slate with no
shared measurement history.

```bash
uv run ado create samplestore -f samplestore.yaml
```

### Document

Use `document` resources to persist markdown or HTML reports in the metastore.
Set `contentType` to `markdown` (default) or `html`. See the
[document resource documentation](https://ibm.github.io/ado/latest/resources/document/).

> The description above is sufficient for creating document resources.
> Only consult the source for advanced options not covered here: read
> `docs/resources/document.md` if the source repo is available, otherwise see
> <https://ibm.github.io/ado/latest/resources/document/>.
Examining skills store their reports this way: put the body in `content`,
optionally set `contentType`, and list related resources in
`relatedResources` with `id` and `role` (`parent` = report is about that
resource; `child` = resource created in response to the document).

```yaml
# <descriptive>_document.yaml  (temp file, not committed)
metadata:
  name: "<descriptive name>"
  description: "<one-line summary>"
contentType: markdown  # or html
content: |
  <full report text>
relatedResources:
  - id: <related resource id>
    role: parent
```

```bash
uv run ado create document -f <descriptive>_document.yaml
uv run ado delete document DOCUMENT_ID
```

Validate with `uv run ado create document -f FILE --dry-run` before creating.

**Querying existing documents** (paths are under `config.`; string candidates
must be single-quoted — see [query-ado-data](../query-ado-data/SKILL.md)):

```bash
# By related resource id
uv run ado get document -q 'config.relatedResources.id=RESOURCE_ID'

# By metadata name
uv run ado get document -q 'config.metadata.name=NAME'
```

Fetch a document's body with
`uv run ado get document DOCUMENT_ID -o yaml`.

When replacing a report, delete the existing document only after the user
agrees and the new report has been created (or immediately before creating the
replacement, if the skill's replace policy says so).

## Related Resources

- [using-ado-cli](../using-ado-cli/SKILL.md) — CLI command syntax and shortcuts
- [define-experiment-campaign](../define-experiment-campaign/SKILL.md) — full
  problem formulation workflow
- [AGENTS.md](../../../AGENTS.md) — YAML testing and linting guidance