agentleFS
Sign inStart free
ScaleDockHQScaleDockHQ/scaledock-skills/skills/openapi-arazzo/SKILL.md

openapi-arazzo

Skill1 starsChanged 31 days agoMITView on GitHub

Arazzo 1.1: describe and run multi-step API workflows over OpenAPI and AsyncAPI operations, with inputs, steps, success criteria, outputs and retry or goto actions. Use when writing, reviewing or executing an arazzo.yaml or arazzo.json, chaining API calls into an end-to-end flow (login then fetch, create then poll, place order then wait for an event), declaring sourceDescriptions of type openapi, asyncapi or arazzo, passing data between steps with runtime expressions ($inputs, $steps, $response.body, $message.payload), writing successCriteria with simple, regex, JSONPath or XPath conditions, adding onSuccess and onFailure actions, using AsyncAPI send and receive steps with correlationId and timeout, upgrading from Arazzo 1.0, or validating against the official Arazzo JSON Schema. Triggers: Arazzo, OpenAPI workflows, arazzo: 1.1.0, workflowId, stepId, successCriteria, operationPath, channelPath, application/vnd.oai.workflows.

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 0 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Prefer operationId over operationPath or channelPath: when the target operation has one (§ 5.8.5.1).

    line 29
  2. Very specific:

    Define each workflow's contract: Write inputs as JSON Schema 2020-12 and name the outputs the caller gets back.

    line 42
  3. Very specific:

    Say what success means: Add successCriteria to every step that can return more than one outcome, and to every AsyncAPI receive step.

    line 48
  4. Very specific:

    Handle the other paths: Add onFailure retries with retryAfter and retryLimit for transient errors, goto for branches, and workflow-level …

    line 51
  5. Very specific:

    references/objects.md: every object and field: root, Info, Source Description, Workflow, Step, Parameter, Success and Failure Actions, …

    line 72

≈ “Common” is an estimate: at least 1 in 5 of the 308,232 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Arazzo Specification

The Arazzo Specification, published by the OpenAPI Initiative (OAI), describes sequences of API calls and their dependencies as workflows over one or more source descriptions (OpenAPI, AsyncAPI or other Arazzo documents). With this skill the agent writes, reviews, validates and executes Arazzo Descriptions.

Follow the workflow below step by step. Every rule here comes from a source in Sources, with the section it cites. Section numbers are those of Arazzo 1.1.0. When a rule and the pinned source disagree, the source wins; when the source has a newer revision than the pin, follow the refresh steps.

Inputs (fill in, or ask before starting)

  • Role: author (writes the description), executor (a tool, test runner or agent that runs workflows), or reviewer.
  • Source descriptions: the OpenAPI and AsyncAPI documents the workflows call, and their operationIds.
  • Revision: the pinned revision in Sources, unless the user names another.
  • Sources: when refreshing this skill or when a rule looks out of date, re-read every URL in Sources first, check spec.openapis.org/arazzo for a newer version or schema iteration, check the v1.2-dev branch for movement, and update the pins.

Invariants

  1. arazzo, info, sourceDescriptions and workflows are REQUIRED, and both lists have at least one entry (§ 5.8.1.1). Tooling MUST interpret the document by arazzo (§ 5.8.1.1).
  2. workflowId is unique in the description and stepId is unique in its workflow; both are case-sensitive and SHOULD match [A-Za-z0-9_\-]+ (§ 5.8.4.1, § 5.8.5.1).
  3. A step targets exactly one of operationId, operationPath, channelPath or workflowId (§ 5.8.5.1). With more than one non-arazzo source description, operationId MUST be written as $sourceDescriptions.<name>.<operationId> (§ 5.8.5.1).
  4. Prefer operationId over operationPath or channelPath when the target operation has one (§ 5.8.5.1).
  5. Every successCriteria entry MUST pass for the step to succeed, and the list is non-empty when present (§ 5.8.5.1, § 5.8.11.4.6).
  6. Defaults: success goes to the next step, failure ends the workflow (§ 5.8.5.1). The first matching action in order is executed (§ 5.8.5.1).
  7. Operation step parameters set in; with a workflowId step, parameters map to the target workflow's inputs (§ 5.8.6.1).
  8. Steps run in an order that satisfies dependsOn and every $steps.<id>.outputs reference (§ 5.8.5.2.4). In a sequential workflow, a reference to a later step's outputs is an error (§ 5.8.5.2.5).
  9. Workflows from other Arazzo documents are listed in sourceDescriptions (§ 5.3) and referenced by $self when the target has one (§ 5.5.2).
  10. Processing a description can perform unsafe operations on arbitrary hosts; the consumer must make sure they are not harmful (§ 6).

Workflow

  1. List the source descriptions. Give each a name, url and type (openapi, asyncapi or arazzo). API URLs come from the source description's servers, not from the Arazzo document (§ 5.7). -> references/objects.md ✓ Every operation the workflows call resolves in one of the listed sources.
  2. Define each workflow's contract. Write inputs as JSON Schema 2020-12 and name the outputs the caller gets back. -> references/objects.md ✓ Every $inputs.* used in steps is declared in inputs.
  3. Write the steps. Point each at one operation or workflow, pass parameters and a request body with runtime expressions, and expose the values later steps need as outputs. -> references/expressions.md, references/examples.md ✓ Invariants 2, 3, 7 and 8 hold.
  4. Say what success means. Add successCriteria to every step that can return more than one outcome, and to every AsyncAPI receive step. -> references/expressions.md, references/asyncapi-steps.md ✓ Each criterion with a type also has a context (§ 5.8.11.5).
  5. Handle the other paths. Add onFailure retries with retryAfter and retryLimit for transient errors, goto for branches, and workflow-level actions for shared handling. Factor repeats into components. -> references/execution.md ✓ Every retry has a limit, and every goto target exists in the same workflow or is a resolvable workflowId.
  6. Validate. Validate against the official Arazzo schema for the declared version, then check what the schema cannot. -> references/versions.md ✓ Schema validation passes, and every reference resolves.
  7. Execute safely (executor role). Run steps in dependency order, evaluate criteria as specified, and treat the description as untrusted input. -> references/execution.md ✓ No step runs against a host or operation the operator has not approved.

Verify before done

  • The description validates against the Arazzo 1.1 schema, iteration 2026-04-15 (references/versions.md).
  • Every operationId, operationPath, channelPath and workflowId resolves in a listed source description (§ 5.8.5.1).
  • Every runtime expression matches the ABNF in § 5.9, and every referenced step output exists on an earlier or dependsOn step (§ 5.8.5.2).
  • Every component key matches ^[a-zA-Z0-9\.\-_]+$ (§ 5.8.9.1), and every Reusable Object reference points to an existing component (§ 5.8.10).
  • Every AsyncAPI step sets action, and every receive step has successCriteria or meets both conditions for omitting it (§ 5.8.5.3).
  • The entry document is named arazzo.yaml or arazzo.json (RECOMMENDED, § 5.3).

Reference index

  • references/objects.md: every object and field: root, Info, Source Description, Workflow, Step, Parameter, Success and Failure Actions, Components, Reusable Object. Load for steps 1 to 3.
  • references/expressions.md: runtime expressions, Criterion conditions and their evaluation, Selector, Expression Type, Request Body and Payload Replacement Objects. Load for steps 3 and 4.
  • references/asyncapi-steps.md: send and receive steps, channelPath, correlationId, timeout, and asynchronous success. Load for step 4.
  • references/execution.md: execution order, action semantics, retries, and security for executors. Load for steps 5 and 7.
  • references/versions.md: 1.0 and 1.1 differences, the official schemas, what a schema cannot check, and the 1.2 development line. Load for step 6.
  • references/examples.md: complete workflows in YAML. Load for step 3.

Related skills

  • openapi for the OpenAPI descriptions that steps call: npx skills add ScaleDockHQ/scaledock-skills --skill openapi.
  • asyncapi for the AsyncAPI descriptions that send and receive steps use: npx skills add ScaleDockHQ/scaledock-skills --skill asyncapi.
  • openapi-overlay to add operationIds or other fields to a source description you cannot edit: npx skills add ScaleDockHQ/scaledock-skills --skill openapi-overlay.

Sources

Status uses the publishing body's own maturity term. Checked is the date the source was last read.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free