instruct — the .instruct file format

.instruct is a file format for agent installation instructions: a versioned, machine-checkable instruction set that a software vendor publishes so that any coding agent (Cursor, Claude Code, Codex, Copilot, Hermes, …) can install and onboard their product on a human's behalf — including a non-technical human.

The motivating case is NVIDIA NemoClaw's agent-guided quickstart (https://docs.nvidia.com/nemoclaw/latest/user-guide/hermes/get-started/quickstart): today that ships as a ~10 KB unstructured Markdown "starter prompt" the user pastes into their coding agent. It works, but nothing about it is standardized, versionable, or checkable. A .instruct file is that same instruction set as a first-class artifact:

• plain Markdown body (written for the agent to follow as prose), with a strict frontmatter envelope (format version, id, targets, approval policy, credential mode, digest-pinned remote assets, declared variants);
• structural safety rules (credential hygiene, per-step verification, variant discipline) that a validator can enforce mechanically;
• a provenance model: remote instruction assets are URL + SHA-256 pinned, and unpinned references fail closed at consumption time.

This repository is the spec-stage prototype: SPEC.md (normative, v0.1), tools/instruct_check.py (stdlib-only reference validator), two examples including a full distillation of the NemoClaw quickstart, and a regression test suite. It is not an installer or an agent runtime — see docs/BOUNDARIES.md.

What a .instruct file looks like

Two parts: a strict YAML-subset frontmatter envelope (machine-checkable) and a plain-Markdown body (written for the agent to follow as prose).

Frontmatter (the envelope)

Required keys:

Key	Meaning
instruct	format version — "0.1" for this spec
id	slug, e.g. nvidia-nemoclaw-hermes
title	human-readable title
version	semver of this instruction set
updated	YYYY-MM-DD last-updated date

Optional keys:

Key	Meaning
vendor, description	publisher and one-line summary
targets	platforms: macos, linux, windows, windows-wsl, web
agents	agent runtimes known compatible (free slugs)
approval	none | destructive | per-step — policy class the body assumes
secrets	none | placeholder | external-form — credential mode
assets	digest-pinned remote instruction assets (URL + SHA-256)
variants	declared conditional branches the body selects between
prerequisites	tools, access, disk, and accounts required before Step 1

Body (canonical sections, in this order)

Section	Required when
## Goal	always
## Interaction Rules	always
## Environment Detection	always
## Variants	iff variants is declared — one ### Variant: <id> block with a Match: condition each
## Prerequisites	optional
## Steps	always — ### Step N: Title blocks, each ending with Verify: lines
## Credentials	iff secrets ≠ none — uses the <PASTE_YOUR_…> placeholder convention
## Verification	always
## Failure and Rollback	always
## References	always (≥ 1 URL)

Unknown H2 sections, out-of-order sections, credential-shaped strings, and unpinned remote assets all fail validation (or warn explicitly) — SPEC.md has the full normative grammar, examples/nemoclaw-hermes.instruct has the real-world version.

Skeleton

---
instruct: "0.1"
id: vendor-product
title: Install Vendor Product
version: "1.0.0"
updated: 2026-09-18
targets: [macos, linux]
secrets: placeholder
variants: [standard]
---

# Install Vendor Product

## Goal
The product is installed and responds.

## Interaction Rules
Ask one question at a time; explain every command; ask permission first.

## Environment Detection
Read-only checks that pick a variant.

## Variants

### Variant: standard
Match: any supported host.

## Steps

### Step 1: Install
Ask permission, then run the installer.
Verify: `product --version` prints a version.

## Credentials
Use `<PASTE_YOUR_API_KEY_HERE>` placeholders; never ask for secrets in chat.

## Verification
Confirm the end state before declaring success.

## Failure and Rollback
Per-failure-class guidance and how to undo.

## References
- Docs: https://example.com/docs

Repository layout

instruct/
├── SPEC.md                       # normative format spec (v0.1)
├── tools/instruct_check.py       # stdlib-only reference validator
├── tests/                        # regression suite (51 cases)
├── examples/
│   ├── minimal.instruct          # smallest valid file
│   └── nemoclaw-hermes.instruct  # full NemoClaw quickstart distillation
├── docs/                         # repo contract (requirements, boundaries, index)
├── project.yaml                  # machine-readable contract
└── AGENTS.md                     # agent operating contract

Quickstart

Requires Python 3.10+ (stdlib only, no install step).

# validate the shipped examples
python3 tools/instruct_check.py examples/minimal.instruct examples/nemoclaw-hermes.instruct

# run the regression suite
python3 -m unittest discover -s tests

# validate any file
python3 tools/instruct_check.py path/to/file.instruct

Status

Prototype — spec v0.1, published at https://github.com/KevinOBytes/instruct. See TODO.md for pending work.

Documentation

Full contract: docs/INDEX.md (question → document router). Required reading for agents: AGENTS.md, docs/BOUNDARIES.md, docs/REQUIREMENTS.md. The format itself: SPEC.md.

License

MIT — see LICENSE.