diff --git a/.agents/skills/petrinaut-shipping/SKILL.md b/.agents/skills/petrinaut-shipping/SKILL.md
new file mode 100644
index 00000000000..c883634ad09
--- /dev/null
+++ b/.agents/skills/petrinaut-shipping/SKILL.md
@@ -0,0 +1,70 @@
+---
+name: petrinaut-shipping
+description: "End-to-end procedure for shipping a change to the Petrinaut packages (libs/@hashintel/petrinaut, petrinaut-core, petrinaut-cli, apps/petrinaut-opt, apps/petrinaut-website): the verification gates per package, the changeset step, docs sync, pre-PR hygiene checks, and CI expectations from draft to ready. Use when implementing any change in these packages, when creating a PR for Petrinaut work, when running tests or lints for them, or when checking CI on a Petrinaut PR."
+license: Apache-2.0
+metadata:
+  triggers:
+    type: domain
+    enforcement: suggest
+    priority: high
+    keywords:
+      - petrinaut
+    intent-patterns:
+      - "\\b(implement|create|fix|add|ship|change)\\b.*?\\bpetrinaut\\b"
+      - "\\bpetrinaut\\b.*?\\b(PR|tests?|lint|CI|checks?)\\b"
+---
+
+# Shipping a Petrinaut change
+
+Standing conventions (changeset policy, docs and diagram placement, CI quirks, the petrinaut-opt boundary) live in `libs/@hashintel/petrinaut/AGENTS.md` and `apps/petrinaut-opt/AGENTS.md`. This skill is the procedure that applies them.
+
+## Gates
+
+Run for every touched package, after every increment:
+
+```sh
+yarn fix:format >/dev/null 2>&1
+npx turbo run build test:unit lint:tsc lint:eslint --filter @hashintel/petrinaut --filter @hashintel/petrinaut-core --filter @hashintel/petrinaut-cli --force --output-logs errors-only
+yarn lint:format
+```
+
+- Trim the `--filter`s to the touched packages; add `--filter @apps/petrinaut-website` when it consumes the change.
+- `build` belongs in that list. `test:unit` depends on `^build`, which builds dependencies and not the selected package, so the React Compiler check, the browser-entry check, and the website's Vite build are otherwise never run.
+- Structure changed (new folder, moved module): also `yarn workspace @local/petrinaut-arch-docs lint:arch-docs`, and add the layer declaration the AGENTS.md architecture section calls for.
+- Arch-docs authored content or `content/diagrams/*.d2` changed: `lint:arch-docs` does not compile MDX or render D2. Run the site build once before pushing: `mise x -- yarn exec turbo run build --filter @apps/petrinaut-docs`. D2 labels containing `:` or `[` must be quoted.
+- Python packages go through Turborepo: `npx turbo run test:unit lint:ruff lint:types --filter @apps/petrinaut-opt --filter @local/petrinaut-python --force`. A plain `uv run pytest` skips the end-to-end tests when the CLI bundle is missing, and skips the comparison of regenerated `openapi.json` that `@apps/petrinaut-opt` runs as part of its own `test:unit`.
+- Formatting is oxfmt via the yarn scripts; never run prettier directly. `yarn lint:format` prints its verdict before its final line, so check the exit code rather than the last line of output.
+
+## Changesets
+
+One `patch` changeset per PR covering the published packages the PR touches (`@hashintel/petrinaut`, `@hashintel/petrinaut-core`); none for pure refactors. Keep the text to one or two plain sentences. See the AGENTS.md conventions for the full policy.
+
+## Docs sync
+
+User-visible behaviour changes update the user guide in the same PR; new pages need registration and a raw import, both test-enforced. The steps are in the "User-facing docs" section of `libs/@hashintel/petrinaut/AGENTS.md`. Doc screenshots cannot be uploaded by an agent: produce candidate captures, list the exact pages and sections to re-capture, and flag "screenshots pending" in the PR body and the summary.
+
+## Pre-PR hygiene
+
+- Read `git diff --stat` against the base: no accidental directories, no unstaged leftovers, no generated output, no `mise.lock` churn.
+- A `Bin` line in the stat for a text file means escape sequences became literal control bytes; fix it before pushing or the diff is unreviewable.
+- A diff too large for one review gets split into stacked PRs, one concern per layer.
+
+## Draft, CI, ready
+
+- Open the PR as a draft, body per the repo PR template.
+- Watch checks until the run settles, and decide that in `jq`. Neither the exit status nor a pending count answers it alone: `gh pr checks` exits non-zero when checks are pending, when they failed, and when none are scheduled yet, and with `--json` it prints `[]` before any exist, so a pending count of zero also reads as "finished" on a PR that has not started.
+
+  ```sh
+  settled='[length, ([.[] | select(.bucket == "pending")] | length)] | .[0] > 0 and .[1] == 0'
+  for _ in $(seq 60); do
+    [ "$(gh pr checks NNNN --json bucket --jq "$settled" 2>/dev/null)" = "true" ] && break
+    sleep 60
+  done
+  gh pr checks NNNN
+  ```
+
+  The wait ends once checks exist and none are pending, failures included, so the table below reports them. Anything else, an empty list or a failed call, keeps waiting. The loop is bounded and the last call keeps its output, so an expired token or an unreachable API surfaces as an error rather than sleeping for ever.
+
+- Judge failures against the CI bullet in the AGENTS.md conventions (Bench-CI non-blocking, the known flaky check, Vercel-side docs failures) before treating them as caused by the diff.
+- Flip to ready only when checks are green. AI reviewers run at that point; triage their threads rather than leaving them unresolved.
+- End any turn that changed the branch by stating what was committed and pushed, or that nothing was.
diff --git a/.claude/hooks/skill-activation-prompt.test.ts b/.claude/hooks/skill-activation-prompt.test.ts
index 36e0f2d22fc..259a1da1d68 100644
--- a/.claude/hooks/skill-activation-prompt.test.ts
+++ b/.claude/hooks/skill-activation-prompt.test.ts
@@ -68,5 +68,17 @@ describe("Skill Activation Snapshots", () => {
     );
   });
 
+  it("activates Petrinaut shipping guidance for Petrinaut work", () => {
+    expect(
+      testSkillActivation("fix the petrinaut simulation engine"),
+    ).toContain("petrinaut-shipping");
+  });
+
+  it("does not activate Petrinaut shipping guidance for a changeset elsewhere", () => {
+    expect(
+      testSkillActivation("add a changeset for the ds-components fix"),
+    ).not.toContain("petrinaut-shipping");
+  });
+
   it("what is the weather today", ({ task }) => createSnapshot(task.name));
 });
diff --git a/.claude/skills/petrinaut-shipping b/.claude/skills/petrinaut-shipping
new file mode 120000
index 00000000000..a58b8ebc99d
--- /dev/null
+++ b/.claude/skills/petrinaut-shipping
@@ -0,0 +1 @@
+../../.agents/skills/petrinaut-shipping
\ No newline at end of file
diff --git a/.claude/skills/skill-rules.json b/.claude/skills/skill-rules.json
index a0f1e1f71ab..7b5114a9578 100644
--- a/.claude/skills/skill-rules.json
+++ b/.claude/skills/skill-rules.json
@@ -193,6 +193,27 @@
       "blockMessage": "Skill is required to proceed",
       "skipConditions": {}
     },
+    "petrinaut-shipping": {
+      "type": "domain",
+      "enforcement": "suggest",
+      "priority": "high",
+      "description": "End-to-end procedure for shipping a change to the Petrinaut packages (libs/@hashintel/petrinaut, petrinaut-core, petrinaut-cli, apps/petrinaut-opt, apps/petrinaut-website): the verification gates per package, the changeset step, docs sync, pre-PR hygiene checks, and CI expectations from draft to ready. Use when implementing any change in these packages, when creating a PR for Petrinaut work, when running tests or lints for them, or when checking CI on a Petrinaut PR.",
+      "promptTriggers": {
+        "keywords": ["petrinaut"],
+        "intentPatterns": [
+          "\\b(implement|create|fix|add|ship|change)\\b.*?\\bpetrinaut\\b",
+          "\\bpetrinaut\\b.*?\\b(PR|tests?|lint|CI|checks?)\\b"
+        ]
+      },
+      "fileTriggers": {
+        "include": [],
+        "exclude": [],
+        "content": [],
+        "create-only": false
+      },
+      "blockMessage": "Skill is required to proceed",
+      "skipConditions": {}
+    },
     "rust-coding-style": {
       "type": "domain",
       "enforcement": "suggest",