hexgate: Skill for Claude Code

Write a Hexgate policy

The user describes intent in prose; you produce a policy YAML that validates, plus a set of dry-run cases that prove it does what they asked. A policy you have not run through the CLI is not finished.

Sources of truth — read the relevant one before using a feature you are unsure of, and prefer them over this file if they disagree:

Workflow

1. Pin down the inputs. You need:

   • the tool names and their argument names/types. Take these from the agent code or its AgentManifest. Otherwise, use what the requester named in their prompt, or ask them;
   • the roles (who calls);
   • the caller attributes available as ctx.*;
   • the shape to write in: a single file, a policies/ dir, or modules.

   Never invent a tool or argument name. A typo'd tool is silently default-denied, and a typo'd arg fails closed. If a name is unknown, ask, or state the assumption explicitly. If the agent's manifest JSON is available, pass it to validate (step 4), which flags tool, skill and argument names the agent doesn't have.

2. Restate the intent as a decision table before writing YAML. List role × tool × condition → ALLOW / DENY / APPROVAL_REQUIRED, plus what happens to anything unlisted. Surface every ambiguity here, e.g. "refunds up to 500 — inclusive? which currency?".

3. Write the YAML. Start deny-by-default and grant the minimum. Put each constraint at the narrowest scope that works (see Where constraints live).

4. Validate until clean:

   uv run hexgate policy validate <file> --max-severity warning [--manifest m.json]
   

   If uv fails building biscuit-python on Python 3.14, add --python 3.13. For a module tree, use uv run hexgate policy check --dir <root> [--manifest m.json] and uv run hexgate policy resolve --dir <root>.

5. Prove it. Turn every row of the decision table into a policy test run, including the negative cases and the boundary values (== limit, limit + 1, missing arg, wrong type):

   uv run hexgate policy test <file> --role billing --tool refund_order \
       --args '{"amount": 500, "currency": "USD"}' [--attributes '{"department": "finance"}'] \
       [--agent-usage '{"invocations_1h": 100}'] [--user-usage '{"invocations_1h": 50}']
   

   Test a usage cap at limit - 1 and at limit, with --agent-usage for agent_usage.* and --user-usage for user_usage.* (a path left out reads zero). Also use --roles a,b to check a multi-role caller, where the most permissive role wins. Pass --engine wasm on every policy test run, since that engine matches production. If it fails because OPA itself is unusable (e.g. opa not found, HEXGATE_OPA_BIN points to…, below the tested floor), drop the flag and say in the report that the production engine went unchecked, and why; any other wasm error is a problem in the policy to fix. Every result must match the table. When one doesn't, fix the policy, not the table, unless the table was wrong.

6. Report. Give the YAML, the decision table with each case's actual CLI result, and any assumptions or residual risks, e.g. "egress on HTTPS is host-level only".