/authoring-action-schema

name: authoring-action-schema
description: "Stand up the Cedar ACTION schema (.cedarschema) a Dogwood deployment governs — its entity types (principals/resources), one action per tool/operation, and each action's context.input/output/system layout — either hand-written or generated from an MCP tools/list manifest. Use when a user needs to declare the entities and actions that policies will scope over, map MCP tools to Cedar actions, or run `dogwood schema mcp`. This is the ACTION schema (entities + actions + context) — the prerequisite for both later skills. Not for writing policies — that is autoformalize-policies. Not for declaring event kinds or information providers (the SERVICE schema) — that is authoring-service-schema. Not for general \"set up Dogwood from scratch\" / \"I don't know where to start\" orientation when no specific entity, action, or MCP manifest is named — route those to the /dogwood orientation command."

Authoring the Cedar action schema for a Dogwood deployment

Your job: produce the **action schema** — a Cedar `.cedarschema` — that declares the world a Dogwood deployment governs: its **entity types** (the principals and resources), **one action per tool/operation**, and each action's **`context`** laid out as `input` / `output` / `system`. This schema is the foundation every policy scopes over, so it comes *first* in the lifecycle: an action schema is **required** before you declare a service schema and before you write any policy.

This is a *modeling* task. The syntax is plain Cedar and fully documented (see [Ground truth](#the-ground-truth-read-before-authoring)) — the hard part is **deciding what your world looks like**: which entities are principals vs resources, what counts as one action, and which fields belong under `input` vs `output` vs `system`. You also choose *how* to produce the file: hand-write it, or **generate it from an MCP `tools/list` manifest**.

Do **not** invent Cedar schema syntax from memory, and do **not** return a schema you have not checked with the `dogwood` CLI. Follow the loop below in order:

1. **Decide the shape** — resolve the modeling questions, and pick hand-write vs MCP-generate ([Step 1](#step-1--decide-the-shape-do-this-first)). 2. **Author or generate** the `.cedarschema` ([Step 2](#step-2--author-or-generate-the-cedarschema)). 3. **Check it** — run `dogwood schema action` and fix until it exits `0`; this is **mandatory** ([Step 3](#step-3--check-the-schema-mandatory--never-skip)). 4. **Hand off** — present the schema and point at the next lifecycle skill ([Step 4](#step-4--output-and-hand-off)).

The ground truth (read before authoring)

The action schema is standard Cedar `.cedarschema` — Dogwood adds **no** schema syntax, only a *convention* for the `context` record. Treat these docs as authoritative; do not guess. Paths are relative to this skill directory (`.claude/skills/authoring-action-schema/`); the guide lives in the `dogwood-docs` crate:

• `../../../dogwood-docs/guide/02-policy-language.md` — read the **"The action

schema"** section: the `namespace`, `entity`/`type`/`action` declarations, the implicit `Action` segment (so `action "Read"` is named `Ns::Action::"Read"`), action group hierarchies (`in [...]`), and the **`context.input` / `context.output` convention** — what `input` vs `output` vs `system` mean and why the grouping matters. This is the 100% reference for a hand-written schema.

• `../../../dogwood-docs/guide/11-mcp-schema-generation.md` — the **MCP

generation** path: the manifest format (a `tools/list` payload or array of tools with `inputSchema` / `outputSchema`), the JSON→Cedar type mapping (`integer`→`Long`, `string`→`String`, `boolean`→`Bool`, `number` + `format: decimal`→`decimal`), and the **Drupe template** the generator layers tools onto (principals, `Gateway` resource, `SystemContext`, and the `Mcp`/`CallTool` action hierarchy). Read this before generating.

• `../../../dogwood-docs/guide/12-cli.md` — the **CLI**: the `dogwood schema`

group (`action`, `mcp`) and `validate`, their flags, `--format human|json`, and the exit-code contract (`0` ok, `1` usage/IO, `2` rejected). If a schema construct is not in these docs, it does not exist — do not use it.

Step 1 — Decide the shape (do this first)

Before writing anything, resolve the modeling questions below. These are the equivalent of policy disambiguation: a wrong answer here silently mis-shapes every policy that scopes over the schema. If you can infer an answer from a supplied MCP manifest or an obvious convention, state your assumption and proceed; otherwise ask the user, tying each question to how it changes the schema.

1. **Which entities are principals vs resources?** Principals are the *actors* (a user, an agent, an IAM entity); resources are what they act *on* (a gateway, a document, a tool endpoint). Declare each as an `entity`, with attributes it carries (`entity OAuthUser = { id: String }`) and optional `tags`. If the same noun could be either, ask — the choice fixes which scope slot (`principal` vs `resource`) a policy uses. 2. **What is one action?** Model **one action per tool or operation** the deployment exposes (`Login`, `Read`, `SellShares`). If two operations differ only in arguments, they are still two actions. Resist collapsing distinct tools into one. 3. **Each action's scope.** For every action, which principal type(s) may perform it (`principal: [OAuthUser]`) and which resource type(s) does it act on (`resource: [Gateway]`)? Does it belong in a **group hierarchy** (`action "Login" in [Action::"CallTool"]`) — the shape the MCP generator produces and the corpus uses? Getting `appliesTo` wrong makes a valid policy fail to type-check. 4. **`context`: what goes in `input` vs `output` vs `system`?** This is the highest-value decision. Follow the convention exactly:

• **`input: <Record>`** — the tool's **arguments** (read in a p