Skip to content

docs: document Skill Workshop tool visibility rules#89932

Open
baskduf wants to merge 2 commits into
openclaw:mainfrom
baskduf:codex/issue-87570
Open

docs: document Skill Workshop tool visibility rules#89932
baskduf wants to merge 2 commits into
openclaw:mainfrom
baskduf:codex/issue-87570

Conversation

@baskduf

@baskduf baskduf commented Jun 3, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Clarify that skill_workshop is already included in tools.profile: "coding".
  • Document the correct fixes for restrictive profiles, provider-scoped profiles, exact allowlists, and sandboxed runs.
  • Update the tool profile/group reference so coding, messaging, and group:agents match the current tool catalog.

Fixes #87570.

Real behavior proof

  • Behavior addressed: Documents Skill Workshop tool visibility accurately for the current OpenClaw tool profile/policy pipeline, including coding profile availability, restrictive profiles, provider-scoped allowlists, and sandboxed runs.
  • Real environment tested: Local OpenClaw source checkout on branch codex/issue-87570 using the actual runtime modules from this patch.
  • Exact steps or command run after this patch: Ran a Node console probe with node --import tsx importing src/agents/tool-catalog.ts and src/agents/openclaw-tools.ts to inspect the live tool profile and constructed tool lists.
  • Evidence after fix (screenshot, recording, terminal capture, console output, redacted runtime log, linked artifact, or copied live output): Console output from the runtime probe:
coding profile includes skill_workshop: true
minimal + alsoAllow includes skill_workshop: true
minimal + alsoAllow also keeps session_status: true
sandboxed coding includes skill_workshop: false
  • Observed result after fix: The copied live output matches the docs: coding includes skill_workshop, alsoAllow adds it to a restrictive profile while preserving the profile's existing tools, and sandboxed runs do not expose skill_workshop.
  • What was not tested: No docs preview server was started; docs checks and markdown lint were run as supplemental verification only.

Verification

  • pnpm docs:list
  • git diff --check
  • pnpm format:docs:check
  • pnpm docs:check-mdx
  • pnpm docs:check-i18n-glossary
  • pnpm lint:docs
  • node --import tsx runtime probe against src/agents/tool-catalog.ts and src/agents/openclaw-tools.ts
  • .agents/skills/autoreview/scripts/autoreview --mode local ... clean

Known gaps

  • pnpm docs:check-links:anchors is currently blocked by Mintlify @mintlify/link-rot failing to import react under this local environment. The added /gateway/config-tools#tool-profiles anchor was checked directly in docs/gateway/config-tools.md.

@openclaw-barnacle openclaw-barnacle Bot added docs Improvements or additions to documentation gateway Gateway runtime size: XS proof: supplied External PR includes structured after-fix real behavior proof. labels Jun 3, 2026
@clawsweeper

clawsweeper Bot commented Jun 3, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Codex review: needs changes before merge. Reviewed June 30, 2026, 4:21 AM ET / 08:21 UTC.

Summary
The PR updates Skill Workshop and gateway docs to describe skill_workshop profile visibility, restrictive-profile fixes, sandboxed-run behavior, and expanded tool profile/group tables.

PR surface: Docs +54. Total +54 across 3 files.

Reproducibility: yes. for the review finding: source inspection shows the runtime catalog includes the expanded agent tools while the policy conformance mirror and current docs still list narrower group:agents semantics. No live user-flow reproduction is needed for this docs consistency issue.

Review metrics: 1 noteworthy metric.

  • Tool Group Mirrors: 2 docs mirrors changed; 1 policy mirror unchanged. The docs tables mirror runtime tool-group semantics, while the policy plugin has a sibling static group map that can silently drift.

Merge readiness
Overall: 🦪 silver shellfish
Proof: 🌊 off-meta tidepool
Patch quality: 🦪 silver shellfish
Result: blocked by patch quality or review findings.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

  • Refresh the branch against current main so the final merge result is reviewable.
  • Sync POLICY_TOOL_GROUPS and focused coverage with the expanded docs, or narrow the docs to runtime-only wording.

Risk before merge

  • [P1] GitHub reports the PR as conflicting/dirty, so maintainers cannot review the final merge result until the branch is refreshed against current main.
  • [P1] If the docs group expansion lands without the policy conformance mirror/test, policy users can see group semantics that disagree with the public tool-policy docs.

Maintainer options:

  1. Refresh And Sync The Policy Mirror (recommended)
    Update the branch against current main and align extensions/policy/src/tool-policy-conformance.ts plus focused coverage with the runtime catalog before landing the docs table expansion.
  2. Scope The Docs To Runtime Only
    If maintainers do not want policy conformance semantics changed here, revise the docs so they clearly describe only the runtime tool catalog and not policy-plugin group conformance.
  3. Close And Track The Remaining Drift Separately
    Because the linked Skill Workshop visibility issue is already shipped, maintainers could close this PR and open a narrower docs/policy-sync item for the remaining catalog drift.
Copy recommended automerge instruction 
@clawsweeper automerge

Special instructions:
Refresh the branch against current main, preserve the shipped Skill Workshop troubleshooting note in docs/tools/skill-workshop.md, and sync extensions/policy/src/tool-policy-conformance.ts plus focused coverage so group:agents and group:openclaw match src/agents/tool-catalog.ts before rerunning docs checks.

Next step before merge

  • [P2] A focused repair can refresh the branch and align the policy conformance map/test with the docs without a product decision.

Security
Cleared: The submitted diff is docs-only and does not change code execution, dependencies, workflows, secrets handling, package metadata, or runtime policy.

Review findings

  • [P2] Sync the policy group mirror — docs/gateway/config-tools.md:43
Review details

Best possible solution:

Refresh the branch, preserve the shipped Skill Workshop visibility note, and either sync POLICY_TOOL_GROUPS plus focused coverage to the runtime catalog or explicitly scope the docs as runtime-only.

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

Yes for the review finding: source inspection shows the runtime catalog includes the expanded agent tools while the policy conformance mirror and current docs still list narrower group:agents semantics. No live user-flow reproduction is needed for this docs consistency issue.

Is this the best way to solve the issue?

No, not as submitted. The docs clarification is useful, but the best fix is to refresh the branch and keep the sibling policy conformance mirror/test aligned or deliberately narrow the docs claim.

Full review comments:

  • [P2] Sync the policy group mirror — docs/gateway/config-tools.md:43
    This updates the public group:agents docs to include goal tools and skill_workshop, but POLICY_TOOL_GROUPS still expands that group to only agents_list and update_plan, and group:openclaw also lacks the goal/Skill Workshop tools. Sync the policy mirror with focused coverage, or make the docs explicitly runtime-only, so policy conformance results do not disagree with the public docs.
    Confidence: 0.88

Overall correctness: patch is incorrect
Overall confidence: 0.87

AGENTS.md: found and applied where relevant.

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

Label changes

Label changes:

  • add rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🌊 off-meta tidepool and patch quality is 🦪 silver shellfish.
  • remove rating: 🦐 gold shrimp: Current PR rating is rating: 🦪 silver shellfish, so this older rating label is no longer current.

Label justifications:

  • P3: This is a low-risk documentation and policy-conformance cleanup with no runtime behavior change in the submitted diff.
  • merge-risk: 🚨 other: The PR expands public tool-group docs while the policy conformance mirror still uses older group semantics.
  • rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🌊 off-meta tidepool and patch quality is 🦪 silver shellfish.
  • status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.
Evidence reviewed

PR surface:

Docs +54. Total +54 across 3 files.

View PR surface stats
Area Files Added Removed Net
Source 0 0 0 0
Tests 0 0 0 0
Docs 3 62 8 +54
Config 0 0 0 0
Generated 0 0 0 0
Other 0 0 0 0
Total 3 62 8 +54

Acceptance criteria:

  • [P1] git diff --check.
  • [P1] pnpm docs:list.
  • [P1] pnpm format:docs:check.
  • [P1] pnpm docs:check-mdx.
  • [P1] pnpm docs:check-i18n-glossary.

What I checked:

Likely related people:

  • vincentkoc: Recent GitHub commit history for the changed Skill Workshop and tools-config docs points to the shipped fix for the linked visibility issue. (role: recent docs contributor; confidence: high; commits: 5f6d4277b157, 21728777dfa0; files: docs/tools/skill-workshop.md, docs/gateway/config-tools.md)
  • steipete: GitHub history for src/agents/tool-catalog.ts shows recent work adding and documenting the goal/tool helpers that the docs table is trying to mirror. (role: recent agent tool catalog contributor; confidence: medium; commits: 5181a9339140, 2ff2ed4099ab, a509c48f0ea2; files: src/agents/tool-catalog.ts)
  • shakkernerd: GitHub history ties the skill_workshop agent tool and Skill Workshop guide to recent feature and rename work in this area. (role: Skill Workshop feature-history contributor; confidence: medium; commits: 2383cfd3039d, 186182fe9e98, e89417d77b54; files: src/agents/tool-catalog.ts, docs/tools/skill-workshop.md)
  • giodl73-repo: GitHub history for extensions/policy/src/tool-policy-conformance.ts points the static policy group map to the original policy posture conformance commit. (role: policy conformance map introducer; confidence: medium; commits: 1e2e6147480c; files: extensions/policy/src/tool-policy-conformance.ts)
What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

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.
Review history (1 earlier review cycle)
  • reviewed 2026-06-21T12:52:40.610Z sha 483f579 :: needs changes before merge. :: [P2] Sync the policy group mirror

@clawsweeper clawsweeper Bot added the rating: 🌊 off-meta tidepool PR readiness rating does not apply to this item. label Jun 3, 2026
@baskduf
baskduf marked this pull request as ready for review June 3, 2026 17:00
@baskduf

baskduf commented Jun 3, 2026

Copy link
Copy Markdown
Contributor Author

@clawsweeper re-review

@clawsweeper

clawsweeper Bot commented Jun 3, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

@baskduf baskduf changed the title [codex] docs: clarify Skill Workshop tool visibility docs: clarify Skill Workshop tool visibility Jun 3, 2026
@clawsweeper clawsweeper Bot added rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. P3 Low-priority cleanup, docs, polish, ergonomics, or speculative work. and removed rating: 🌊 off-meta tidepool PR readiness rating does not apply to this item. labels Jun 3, 2026
@baskduf baskduf changed the title docs: clarify Skill Workshop tool visibility docs: document Skill Workshop tool visibility rules Jun 3, 2026
@baskduf
baskduf requested a review from a team as a code owner June 4, 2026 02:28
@openclaw-barnacle openclaw-barnacle Bot added the docker Docker and sandbox tooling label Jun 4, 2026
@clawsweeper clawsweeper Bot added rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. merge-risk: 🚨 other 🚨 Merging this PR has meaningful risk outside the owned taxonomy. and removed rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. labels Jun 15, 2026
@clawsweeper clawsweeper Bot mentioned this pull request Jun 19, 2026
Open
@clawsweeper clawsweeper Bot added rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. and removed rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. labels Jul 6, 2026
@openclaw-barnacle

openclaw-barnacle Bot commented Jul 20, 2026

Copy link
Copy Markdown

This pull request has been automatically marked as stale due to inactivity.
Please add updates or it will be closed.

@openclaw-barnacle openclaw-barnacle Bot added the stale Marked as stale due to inactivity label Jul 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

docker Docker and sandbox tooling docs Improvements or additions to documentation gateway Gateway runtime merge-risk: 🚨 other 🚨 Merging this PR has meaningful risk outside the owned taxonomy. P3 Low-priority cleanup, docs, polish, ergonomics, or speculative work. proof: supplied External PR includes structured after-fix real behavior proof. rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. size: XS stale Marked as stale due to inactivity status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Skill Workshop loaded but skill_workshop tool hidden by coding profile lacks actionable diagnostic

2 participants

@baskduf @Patrick-Erichsen