loop-worker — Claude Code skill: what it does, how to install
Runs Ruflo background workers on a /loop schedule and checks them through MCP. Use it for recurring code checks and worker tasks.
npx skills add ruvnet/ruflo --skill loop-worker -a claude-codeWhat loop-worker does
This skill runs Ruflo background workers through Claude Code's native /loop. It sends a worker name to mcp__plugin_ruflo-core_ruflo__hooks_worker-dispatch and checks progress with hooks_worker-status. Its 12 workers include audit, optimize, testgaps, map, document, and refactor.
For a prompt cache with a 5-minute TTL, it suggests a 270s delay. With a 1-hour TTL, it switches to polling every 1200-1800s; heavier analysis workers have a suggested 600s cadence. The loop stops through ScheduleWakeup({ stop: true }) after a worker reports nothing new twice.
Long background jobs send their own completion notification. Short ScheduleWakeup polls are therefore the wrong choice for them, so use a fallback delay of 1200s or more. MCP responses can include [LOOP_SUGGESTION] and [CRON_SUGGESTION] hints that the loop follows.
What it helps with
- run recurring security audits through
/loop - check a background worker's status through MCP
- schedule another iteration after dispatching a worker
- stop a loop after two empty worker reports
- choose a polling delay for the prompt cache TTL
Example prompts for the agent
- Run
/loop auditand check the background worker status. - Start
/loop mapto map the codebase. - Run
/loop testgapsand stop the schedule after two reports with nothing new.
How to install loop-worker
1Skills CLI (Vercel)
npx skills add ruvnet/ruflo --skill loop-worker -a claude-code2Manually: put the files in place
~/.claude/skills/loop-worker/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/loop-worker/
1Skills CLI (Vercel)
npx skills add ruvnet/ruflo --skill loop-worker -a codex2Manually: put the files in place
.agents/skills/loop-worker/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add ruvnet/ruflo --skill loop-worker -a cursor2Manually: put the files in place
.cursor/skills/loop-worker/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install ruvnet/ruflo loop-worker2Manually: put the files in place
.github/skills/loop-worker/SKILL.md1Skills CLI (Vercel)
npx skills add ruvnet/ruflo --skill loop-worker -a gemini-cli2Platform CLI
gemini skills install https://github.com/ruvnet/ruflo --path plugins/ruflo-loop-workers/skills/loop-workerManually: put the files in place
.devin/skills/loop-worker/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add ruvnet/ruflo --skill loop-worker -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about loop-worker
How do I install loop-worker in Claude Code?
Run npx skills add ruvnet/ruflo --skill loop-worker -a claude-code, then run npx skills add ruvnet/ruflo --skill loop-worker -a claude-code again. The skill file is at ~/.claude/skills/loop-worker/SKILL.md.
What does loop-worker do?
It dispatches Ruflo workers through MCP, checks their status, and schedules another iteration with /loop and ScheduleWakeup.
When does loop-worker stop a scheduled loop?
It stops when a worker reports nothing new twice in a row. The stop action uses ScheduleWakeup({ stop: true }).
Source text
SKILL.md · MIT
---
name: loop-worker
description: Run Ruflo background workers using Claude Code native /loop scheduling
argument-hint: "<worker-name>"
allowed-tools: Bash(npx *) mcp__plugin_ruflo-core_ruflo__hooks_worker-dispatch mcp__plugin_ruflo-core_ruflo__hooks_worker-status ScheduleWakeup
---
Use `/loop` for in-session periodic workers. Pick the delay from what you are waiting for:
- With the 5-minute prompt-cache TTL, `min(270, cache_ttl * 0.9)` = 270s keeps the cache warm (ruflo-autopilot ADR-0001 owns that heartbeat).
- If the `ScheduleWakeup` tool description says this session uses the 1-hour TTL, a 270s wake buys nothing; poll at 1200-1800s unless the worker finishes faster.
Dispatch a worker via MCP: `mcp__plugin_ruflo-core_ruflo__hooks_worker-dispatch({ trigger: "WORKER_NAME" })`. It runs in the background by default (`background: true`), so check on it with `hooks_worker-status` instead of waiting inline.
Then schedule the next iteration. `ScheduleWakeup` needs the loop prompt back so the next firing re-enters the loop:
`ScheduleWakeup({ delaySeconds: 270, reason: "next WORKER_NAME iteration", prompt: "/loop <the same /loop input>", noop: false })`
Stop the loop when the worker reports nothing new twice in a row: `ScheduleWakeup({ stop: true })`.
### Available Workers (12, per ADR-0001 and `/ruflo-loop`)
| Worker | Priority | Interval | Description |
|--------|----------|----------|-------------|
| audit | critical | 270s | Security analysis |
| optimize | high | 270s | Performance optimization |
| predict | normal | 270s | Predictive preloading |
| testgaps | normal | 270s | Test coverage analysis |
| ultralearn | normal | 600s | Deep knowledge acquisition |
| deepdive | normal | 600s | Deep code analysis |
| map | normal | 600s | Codebase mapping |
| document | normal | 600s | Auto-documentation |
| refactor | normal | 600s | Refactoring suggestions |
| benchmark | normal | 600s | Performance benchmarking |
| consolidate | low | 600s | Memory consolidation |
| preload | low | 270s | Resource preloading |
The intervals are suggested cadences, not enforced by the dispatcher: 270s keeps the prompt cache warm, and the heavier analysis workers run at 600s because one iteration rarely finishes sooner.
Work you start in the background (a build, a long job) finishes with its own completion notification. Do not poll it with short `ScheduleWakeup` calls; use a long fallback delay (1200s or more) so the loop survives a hung job.
MCP tool responses include `[LOOP_SUGGESTION]` and `[CRON_SUGGESTION]` hints -- follow them.
© ruvnet · MIT · ruvnet/ruflo
