Make Peekaboo skill docs the single source of truth for OpenClaw agent use

[coygeek]

Summary

There are currently two Peekaboo skill documents that appear to overlap:

• openclaw/Peekaboo: https://github.com/openclaw/Peekaboo/blob/main/skills/peekaboo/SKILL.md
• openclaw/openclaw: https://github.com/openclaw/openclaw/blob/main/skills/peekaboo/SKILL.md

This is confusing for agentic use because it is not obvious which file should be treated as canonical when Peekaboo command surfaces or recommended workflows change.

Why this matters

The Peekaboo project is likely the more up-to-date source for Peekaboo-specific behavior, command docs, validation workflows, and agent guidance. If OpenClaw keeps a separate copy of similar guidance, it can drift and cause agents to follow stale instructions.

Suggested direction

Use the Peekaboo repo's skill file as the single source of truth for Peekaboo-specific guidance:

• Keep canonical Peekaboo skill guidance in openclaw/Peekaboo.
• Change the openclaw/openclaw Peekaboo skill to point to or consume the canonical Peekaboo skill instead of duplicating command/workflow reference content.
• Keep only OpenClaw-specific integration details in openclaw/openclaw, such as the OpenClaw bridge socket behavior, if that context cannot live cleanly in the Peekaboo repo.
• Add a small note in both places explaining the ownership boundary so future updates do not reintroduce drift.

Acceptance criteria

• There is a clear canonical owner for Peekaboo agent skill guidance.
• OpenClaw-specific guidance references the canonical Peekaboo skill instead of duplicating broad Peekaboo command documentation.
• Contributors and agents can tell where to update Peekaboo skill behavior when the CLI changes.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed June 26, 2026, 5:13 PM ET / 21:13 UTC.

Summary
Keep open: current Peekaboo main made the local skill thinner, but OpenClaw still bundles duplicated Peekaboo command guidance and a collaborator raised a real distribution constraint that needs maintainer direction.

Reproducibility: yes. Source inspection shows Peekaboo's local skill now prefers live canonical references, while the OpenClaw bundled skill still vendors broad Peekaboo command and workflow content.

Root-cause cluster
Relationship: canonical
Canonical: #198
Summary: This issue is the canonical remaining cross-repository skill ownership question; the stale local skill-path issue and its merged PR only partially overlap.

Members:

• partial_overlap: docs/agent-skill.md points users at missing skills/peekaboo-cli directory #195 - The closed issue covered the narrower stale skills/peekaboo-cli path in Peekaboo docs, not the unresolved OpenClaw bundled-skill ownership model.
• partial_overlap: docs: refresh Peekaboo agent skill guidance #197 - The merged PR fixed the Peekaboo-side docs refresh and stale path, but did not make OpenClaw defer to Peekaboo as the single source of truth.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Next step
This should stay with maintainer review because the remaining choice spans two repositories and OpenClaw's bundled-skill distribution model.

Review details

Best possible solution:

Maintainers should choose a distribution-safe ownership model: either generate or vendor OpenClaw's bundled skill from Peekaboo with clear sync ownership, or keep a thin OpenClaw wrapper with explicit boundary notes in both repositories.

Do we have a high-confidence way to reproduce the issue?

Yes. Source inspection shows Peekaboo's local skill now prefers live canonical references, while the OpenClaw bundled skill still vendors broad Peekaboo command and workflow content.

Is this the best way to solve the issue?

Unclear. Making Peekaboo the canonical guidance source is directionally sound, but the collaborator comment means the maintainable fix first needs a distribution decision for OpenClaw's bundled skills.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The remaining acceptance criteria spans both Peekaboo and OpenClaw, so a Peekaboo-only docs change would still leave OpenClaw's bundled skill as a drift source.
• A direct pointer to the Peekaboo checkout may not fit OpenClaw's distribution model because OpenClaw ships with skills and should run without a Peekaboo source checkout.

Codex review notes: model internal, reasoning high; reviewed against dda07c245fea.

Label changes

Label changes:

• add clawsweeper:fix-shape-clear: Current issue advisory state selects this label.

Label justifications:

• P3: This is a low-risk documentation and ownership-boundary cleanup, not a runtime regression.
• impact:other: The impact is agent guidance drift across repositories, which is maintainer-visible but outside the specific owned impact taxonomy.

Evidence reviewed

What I checked:

• Current Peekaboo skill is already thinner: Current main tells agents to prefer the repo binary, live help, peekaboo learn, peekaboo tools, command docs, permissions docs, bridge docs, and AGENTS.md over copied command references. (skills/peekaboo/SKILL.md:8, dda07c245fea)
• Current install docs identify the local canonical skill: Current main points installation and maintenance docs at skills/peekaboo/SKILL.md and says the skill should stay compact rather than vendoring generated command catalogs. (docs/agent-skill.md:10, dda07c245fea)
• OpenClaw skill still duplicates broad Peekaboo guidance: The OpenClaw bundled skill still includes feature lists, global flags, quickstarts, targeting parameters, and examples beyond the OpenClaw Bridge-specific setup, so the cross-repo drift concern remains observable. (openclaw/openclaw:skills/peekaboo/SKILL.md:48, 66079161d72a)
• Maintainer discussion leaves the direction unresolved: A collaborator commented that OpenClaw is distributed with skills and should not require a Peekaboo checkout to run, which blocks the issue's direct single-source proposal from being a mechanical docs fix.
• Merged local docs refresh only partially addressed the request: Merged PR 197 refreshed the Peekaboo-side skill and closed the narrower stale skills/peekaboo-cli path issue, but it did not make OpenClaw's bundled skill consume or point to Peekaboo as the single source of truth. (docs/agent-skill.md:19, 1771d7db349b)
• History ties the current local guidance to PR 197: Git blame and commit history show the current local thin-skill wording and install-path updates came from the merged docs refresh, while later main changes only adjusted opaque element-ID wording. (docs/agent-skill.md:10, 1771d7db349b)

Likely related people:

• steipete: Recent Peekaboo skill guidance commits and the issue comment both point to this person as connected to the unresolved bundled-skill distribution boundary. (role: recent area contributor; confidence: high; commits: dda07c245fea, 66079161d72a, 8b53988912d7; files: skills/peekaboo/SKILL.md, docs/agent-skill.md, openclaw/openclaw:skills/peekaboo/SKILL.md)
• coygeek: Merged PR 197 refreshed the local Peekaboo skill and install docs, which partially addressed the local side of this issue's drift concern. (role: recent docs contributor; confidence: medium; commits: 1771d7db349b; files: docs/agent-skill.md, skills/peekaboo/SKILL.md)
• terryso: GitHub path history shows the original Peekaboo CLI agent skill and install doc were added in the earlier agent-skill commit, including the older skill naming that later drifted. (role: introduced behavior; confidence: medium; commits: 59ec493c334b; files: docs/agent-skill.md, skills/peekaboo-cli/SKILL.md)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[steipete]

Unsure how to fix, since OpenClaw is distributed with skills and it shouldn't need a peekaboo checkout to run.