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

# Author an Agent project

> Inspect, compile, and evaluate declarative Agent intent with the version-matched CLI workflow.

An Agent authoring project is a local source format that compiles into the governed [Agent and AgentBlueprint](/concepts/agent-blueprints) model. The source tree and `.checkfu` outputs are inspectable authoring material; neither is runtime authority.

<Warning>
  The Checkfu CLI has no self-service public installation channel during private alpha. Every command below assumes a Checkfu source checkout or a private artifact supplied through an explicitly authorized alpha arrangement. Read [CLI access](/getting-started/cli-access) before continuing. If you do not have CLI access, use the [HTTP contract](/reference/overview) and public schemas instead of inventing an install command.
</Warning>

If the task also includes customer-side Slack, Custom-tool server, or embedded UI code, inspect the bundled integration catalog first:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
checkfu add --list
```

Recipes remain write-nothing integration instructions. This guide owns declarative Agent intent; [use Checkfu with your coding agent](/guides/use-checkfu-with-your-coding-agent) explains when to install the version-matched authoring skill.

## Project tree

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
checkfu.json
agent/
  agent.json            # optional
  instructions.md
  tools/<tool-name>.json
  skills/<skill-name>.json
scenarios/<scenario-name>.json
```

`agent/instructions.md` is the only file under `agent/` that is required. `checkfu.json` already declares the harness, model routing profile, and environment, so a project with nothing but a page of markdown under `agent/` compiles: the name comes from the page's leading `# Title`, and everything else takes its default. Add `agent/agent.json` when the agent needs tools, skills, or a policy that page cannot carry.

`agent/agent.json` follows the canonical Agent manifest, except `name` is optional. Tool and skill identity comes from the path: omit a redundant `name`, or make it exactly match `<tool-name>` / `<skill-name>`. `checkfu.json` owns the Blueprint package, and each file under `scenarios/` declares an acceptance scenario that travels with it.

Keep credentials out of every file. A Blueprint declares credential requirements; values enter only through the governed write-only operation for the bound resource.

## Inspect before editing

Run inspection before changing source, and keep the JSON result for comparison:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
checkfu agent info . --json
```

Inspection reports the source format, normalized Agent and Blueprint identity, release hash, tools, skills, scenarios, diagnostics, required Connections, and compatibility requirements. The compiler defaults `blueprint`, `agent`, `tool`, `skill`, and `scenario` authoring capabilities to epoch 1. Declare a different epoch under `compatibility` in `agent/agent.json` only when the project genuinely requires it. Never downgrade an epoch merely to make compilation pass.

## Compile and inspect the immutable generation

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
checkfu agent compile .
jq . .checkfu/current.json
```

Compilation atomically writes an operation-unique generation under the compiled release digest in `.checkfu/compile/`, then updates `.checkfu/current.json`. Follow that pointer and inspect the canonical package, diagnostics, inspection, and compatibility documents. Do not assume source was accepted because the command produced some output; compilation fails closed on unsupported capabilities, path/name drift, staging problems, or symlinked artifact roots.

A behavior change becomes effective through the next immutable Agent version
and ordinary Session Version pinning. Local source and compiled files never
replace that authority.

## Plan and run the declared scenarios

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
checkfu eval .
```

This validates the declared scenarios and materializes a plan bound to the exact compiled `release_hash`. Run every planned scenario against the intended Target—for example an authorized local worker or admitted deployment—and read settlement from the Session event log. A failed scenario is a failed evaluation; do not grade from response timing or silently omit a case. [Outcomes](/concepts/outcomes) may supply a platform verdict when a scenario declares one, but the CLI does not create a second grader.

Record exactly one observation per declared scenario. The minimal closed document is:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "kind": "checkfu-agent-eval-observations",
  "version": 1,
  "release_hash": "sha256:<compiled-release-digest>",
  "scenarios": [
    {
      "name": "scenario-name",
      "passed": true,
      "cost_tokens": 120,
      "latency_ms": 950,
      "source_report": {
        "kind": "checkfu-unverified-scenario-report",
        "version": 1,
        "target": { "kind": "worker", "name": "release-worker" },
        "session": "sess_<id>",
        "run": "run_<id>",
        "events": {
          "from_sequence": 1,
          "to_sequence": 12,
          "digest": "sha256:<event-log-digest>"
        }
      }
    }
  ]
}
```

Then bind the observations to the current plan:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
checkfu eval . --observations observations.json --json
```

The observations input must be a regular UTF-8 JSON file no larger than 1 MiB.
Oversized or non-regular input is refused before local evidence is written.

Evaluation writes its own generation and pointer, separate from the compile pointer: follow `.checkfu/eval-current.json` to the generation holding `plan.json` and, once observations are bound, `evidence.json`. That pointer also carries the `planned` / `passed` / `failed` status.

The resulting `.checkfu/eval/.../evidence.json` is labeled `unverified-caller-reported`. The CLI validates shape, complete scenario coverage, and release binding, but it does not independently re-read the Target event log or emit promotion-grade `ReleaseEvaluation` evidence. Treat `source_report` as a caller assertion.

## Agent contract

* Inspect before editing, and compare the compiled generation with your intent.
* Follow path-derived tool and skill names; do not create a second identity in JSON.
* Never weaken compatibility epochs to pass compile.
* A failed or missing scenario is a failed evaluation.
* Never put credentials in source, artifacts, or observations.
* Never run local authoring code in the Checkfu control plane, Runner, or Sandbox.
* Never commit or upload `.checkfu` artifacts, observations, or evidence without explicit authorization.

For the installed-version repair workflow and complete optional Outcome fields, follow the shipped `checkfu-agent-authoring` skill. Locate the version-matched copies, and the authoring capability epochs your CLI supports, with:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
checkfu agent docs --json
```

That prints the on-disk paths to the bundled guide and skill rather than fetching anything, so it stays correct offline and cannot drift from the binary you are running. [The coding-agent guide](/guides/use-checkfu-with-your-coding-agent) covers installing the skill into an agent. This page is the human-readable route into the same stable contract.