Create a self-improvement skill for claw sweeper

[Takhoffman]

Goal

Create a new skill that helps the agent improve itself over time, but only after first studying the clawsweeper codebase and understanding how the agent currently works.

The skill should not start from a generic “self-improvement” template. It must be grounded in the actual architecture, conventions, runtime flow, skill loading model, agent prompts/instructions, tool boundaries, test setup, and repository practices used by this repo.

Required first step: study the codebase

Before designing or implementing the skill, the implementer/agent must inspect the repo and produce a short findings summary covering:

• How the clawsweeper agent is started and configured
• Where skills live and how they are discovered/loaded/invoked
• What files define agent behavior, prompts, instructions, or policies
• How the repo expects changes to be tested or validated
• What safety boundaries exist around file edits, command execution, GitHub operations, and automation
• Any existing docs, examples, or conventions that a new skill should follow

Skill behavior

The new skill should help the agent identify useful improvements to itself by analyzing its own operation and the surrounding repo context. At minimum, it should be able to:

• Inspect the current codebase before recommending changes
• Identify opportunities to improve prompts, skills, tooling, tests, docs, or workflows
• Separate low-risk improvements from risky architectural changes
• Produce actionable recommendations with exact files/functions/modules to inspect or modify
• Prefer small, reviewable changes over broad speculative rewrites
• Explain why each proposed improvement is likely to help the agent
• Avoid making self-modifications blindly or recursively without human review

Expected output of the skill

When invoked, the skill should produce something like:

1. Codebase understanding summary — what it found about how the agent works
2. Improvement candidates — ranked by impact, risk, and ease
3. Recommended next action — one small change to make first
4. Validation plan — how to test that the change actually helped
5. Safety notes — what not to change automatically without review

Acceptance criteria

• A new skill exists in the repo following existing skill conventions
• The skill explicitly requires a codebase study phase before suggesting improvements
• The skill documents the exact areas/files it inspected before making recommendations
• The skill produces ranked, actionable self-improvement suggestions
• The skill includes guardrails against unreviewed recursive self-modification
• The skill includes a validation/test plan for proposed improvements
• Any docs or examples needed to invoke the skill are added or updated

Non-goals

• Do not build an autonomous self-modifying loop in this issue
• Do not let the skill silently rewrite core agent behavior without review
• Do not create generic advice disconnected from the clawsweeper repo
• Do not require external services unless the existing project architecture already does

Notes

This should be treated as an agent-first repo maintenance skill: it should make the agent better at understanding and improving its own codebase, while keeping changes reviewable, explainable, and safe.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed May 30, 2026, 9:21 PM ET / 01:21 UTC.

Summary
Keep open: current main does not contain the requested self-improvement skill, and the ClawSweeper repository profile only allows issue cleanup when the requested issue behavior is already implemented on main.

Reproducibility: not applicable. this is a request for a new skill, not a bug with runtime behavior to reproduce. The current-main check is source inspection for whether that skill already exists.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.

Next step
Maintainers should first decide whether a self-improvement skill belongs in this repo-local skill set or should live outside the core ClawSweeper source tree.

Review details

Best possible solution:

If maintainers want this in-tree, add a narrow .agents/skills/self-improvement/SKILL.md with mandatory codebase-study steps, explicit inspected areas, ranked recommendations, validation guidance, and clear no-recursive-self-modification guardrails.

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

Not applicable: this is a request for a new skill, not a bug with runtime behavior to reproduce. The current-main check is source inspection for whether that skill already exists.

Is this the best way to solve the issue?

Unclear until maintainer direction: the issue gives useful guardrails, but adding an automatically discoverable self-improvement skill is a product/workflow choice for this repository.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• No VISION.md is present, so roadmap fit for adding a repo-local self-improvement skill is not settled by repository vision policy.
• The request is intentionally safety-sensitive in shape: implementation should stay to a skill/documentation workflow and avoid any autonomous self-modifying loop.

Codex review notes: model gpt-5.5, reasoning high; reviewed against efbf47f1aaf7.

Label changes

Label changes:

• add P3: This is a low-risk optional skill/workflow feature request with no reported production regression or user-facing breakage.
• add issue-rating: 🌊 off-meta tidepool: Current issue advisory state selects this label.
• add clawsweeper:no-new-fix-pr: Current issue advisory state selects this label.
• add clawsweeper:needs-maintainer-review: Current issue advisory state selects this label.
• add clawsweeper:needs-product-decision: Current issue advisory state selects this label.

Label justifications:

• P3: This is a low-risk optional skill/workflow feature request with no reported production regression or user-facing breakage.

Evidence reviewed

What I checked:

• Issue request: The issue asks for a new skill with an explicit codebase-study phase, ranked self-improvement suggestions, validation planning, and guardrails against unreviewed recursive self-modification.
• Existing repo-local skill surface: Current main has only one repo-local SKILL.md, the Crabbox skill; there is no existing self-improvement skill to treat as implemented. (.agents/skills/crabbox/SKILL.md:1, efbf47f1aaf7)
• No matching implementation found: A source/docs search for self-improvement, self modification, recursive self-modification, and the requested output headings found no matches on current main. (efbf47f1aaf7)
• Repository profile keeps ClawSweeper issues conservative: The openclaw/clawsweeper profile says to keep everything else open for maintainer triage and permits issue auto-close only for implemented_on_main. (config/target-repositories.json:16, efbf47f1aaf7)
• Repair lane excludes product-choice feature work from automatic bug implementation: The work-lane docs exclude mixed feature/config/product work from strict bug automation and require VISION.md evidence for the small feature/docs/cleanup lane. (docs/work-lane.md:85, efbf47f1aaf7)
• No VISION.md for product-fit anchoring: The target checkout has no VISION.md, so this new skill's roadmap fit cannot be marked aligned for automatic feature implementation. (efbf47f1aaf7)

Likely related people:

• Takhoffman: Commit 4954daa introduced the current repo-local Crabbox skill, repair prompt assembly, and worker-system prompt lines most relevant to a new ClawSweeper skill. (role: skill convention and repair prompt introducer; confidence: high; commits: 4954daa585f1; files: .agents/skills/crabbox/SKILL.md, src/repair/lib.ts, prompts/repair/worker-system.md)
• Peter Steinberger: Recent commits touched the README and commit-review lane documentation that describe ClawSweeper self-review and operational boundaries a self-improvement skill would need to respect. (role: recent ClawSweeper operations/docs contributor; confidence: medium; commits: 558017d383b7, 060b088637f7; files: README.md, .github/workflows/sweep.yml)

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.