---
name: shodai-agreements
description: Use when building with Shodai Agreements API, authoring agreement JSON, validating or preflighting deployments, deploying or operating agreements, debugging API errors, using the playground, or inspecting existing agreement state and history.
metadata:
  version: "1.0"
---

# Shodai Agreements Skill

Use this skill to build, test, debug, and operate Shodai agreements. Shodai turns agreement definitions into executable, verifiable state machines through agreement JSON, an EVM execution layer, a REST API, and the `@cns-labs/agreements-api-client` TypeScript SDK.

## Classify the task first

Choose the user's primary mode before acting:

- New quickstart or first experiment
- Existing project integration
- Existing agreement inspection
- Existing agreement operation
- Agreement JSON authoring
- Deployment or signing debugging
- API, auth, or key issue
- Browser playground experiment
- Demo app or product workflow exploration

Do not force onboarding if the user already has `API_KEY`, project files, an agreement ID, a deployed address, an error response, or a clear task. Use the provided context and go directly to the relevant workflow.

## Source hierarchy

Use these sources in order:

1. This skill for routing, constraints, and workflow defaults.
2. `https://docs.shodai.network/llms.txt` for the generated page index.
3. Relevant page-level Markdown exports, such as `https://docs.shodai.network/quickstart.md`.
4. `https://docs.shodai.network/openapi.json` for exact routes, schemas, servers, and response shapes.
5. `https://docs.shodai.network/llms-full.txt` only as fallback context.

Prefer the SDK docs and typed client methods for TypeScript work. Use raw HTTP when the user is not using TypeScript or when debugging transport-level behavior.

## Autonomy and credentials

Use an existing `API_KEY` from the environment or local project context when available.

If the user has delegated setup and browser automation is available, you may use `https://developers.shodai.network/portal` to obtain testnet API access.

Handle credentials according to the user's environment and normal secret-handling conventions. Do not add confirmation steps solely because the task is a testnet onboarding flow.

## Workflow defaults

For a first working experiment:

1. Load docs context from `llms.txt`, this skill, the Quickstart, the TypeScript client page, examples, deployment and operation pages, troubleshooting, and OpenAPI.
2. Use the SDK-first TypeScript path with `@cns-labs/agreements-api-client` and `viem`.
3. Use `ApiClient` with `environment: 'testnet'` unless the user provides another host or environment.
4. Confirm health and authenticated list access, then continue to a meaningful proof.
5. Use a real example agreement from the docs when an example artifact is needed.
6. Run template validation and deployment preflight before signing.
7. Deploy and submit an input when credentials and signing context are available; otherwise stop at the strongest completed proof.

For existing agreement work, fetch the agreement record, current state, input history, and agreement JSON before choosing an action. Choose input IDs, values, issuer rules, state IDs, and lifecycle expectations from the agreement JSON and docs, not from guesses.

For debugging, start from the user's error response, stack trace, request, or code. Read the relevant docs and OpenAPI details before changing code or retrying the full flow.

## Do not invent protocol details

Do not invent API routes, request bodies, agreement JSON shape, state IDs, input IDs, issuer rules, lifecycle behavior, nonce handling, or signing payloads. Use docs examples, OpenAPI, SDK types, and retrieved agreement records as the source of truth.

## Reporting

Default to a concise evidence receipt:

- what completed
- relevant IDs, statuses, state, address, or chain when useful
- blocker or next action

Include docs used, full command logs, or long transcripts only when debugging, reproducing a result, or when the user asks.