From 38e56972cd90b793c9f45ab52a6e63c45f4f7aa5 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Wed, 29 Apr 2026 03:23:17 +0100
Subject: [PATCH] docs: document Clownfish comment commands

---
 .agents/skills/clownfish-cloud-pr/SKILL.md | 31 ++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/.agents/skills/clownfish-cloud-pr/SKILL.md b/.agents/skills/clownfish-cloud-pr/SKILL.md
index 3e0c6665f0c..06ccc9a2dcf 100644
--- a/.agents/skills/clownfish-cloud-pr/SKILL.md
+++ b/.agents/skills/clownfish-cloud-pr/SKILL.md
@@ -49,6 +49,37 @@ Do not use `--dispatch` until the job is committed and pushed; the workflow
 reads the job path from GitHub. Keep `CLOWNFISH_ALLOW_MERGE=0` unless Peter
 explicitly opens the merge gate.
 
+## Maintainer Comment Commands
+
+Clownfish can also be asked from target repo comments, but only by maintainers.
+Use `/clownfish ...` or `@openclaw-clownfish ...`; do not use `@clownfish`
+because that is a separate GitHub user.
+
+Supported commands:
+
+```text
+/clownfish status
+/clownfish fix ci
+/clownfish address review
+/clownfish rebase
+/clownfish explain
+/clownfish stop
+@openclaw-clownfish fix ci
+```
+
+The router accepts `OWNER`, `MEMBER`, and `COLLABORATOR` comments by default.
+Contributor comments are ignored without a reply. Repair commands dispatch
+`cluster-worker.yml` only for existing Clownfish PRs with the `clownfish` label
+or `clownfish/*` branch.
+
+```bash
+npm run comment-router -- --repo openclaw/openclaw --lookback-minutes 180
+npm run comment-router -- --repo openclaw/openclaw --execute --wait-for-capacity
+```
+
+Scheduled routing stays dry until `CLOWNFISH_COMMENT_ROUTER_EXECUTE=1` is set in
+`openclaw/clownfish` repo variables.
+
 ## Guardrails
 
 - One cluster, one branch, one PR: `clownfish/<cluster-id>`.