ralph-loop
Use when performing ralph wiggum style long-running development loops with pacing control.
How do I install this agent skill?
npx skills add https://github.com/zenobi-us/dotfiles --skill ralph-loopIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill defines a management system for long-running iterative development loops. It maintains state in a local hidden directory and orchestrates task completion via subagents. No malicious patterns or security risks were identified.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerwarn
1/1 file flagged
What does this agent skill do?
Ralph Wiggum - Long-Running Development Loops
Long-running iterative development loops with pacing control.
When to Use
- Complex tasks requiring multiple iterations
- Tasks with many discrete steps that build on each other
- Work that benefits from periodic reflection
Do NOT use for simple one-shot tasks or quick fixes.
Agent Tool
Call ralph_start to begin a loop on yourself:
ralph_start({
name: "loop-name",
taskContent: "# Task\n\n## Goals\n- Goal 1\n\n## Checklist\n- [ ] Item 1\n- [ ] Item 2",
maxIterations: 50, // Default: 50
itemsPerIteration: 3, // Optional: suggest N items per turn
reflectEvery: 10, // Optional: reflect every N iterations
useSubagents: true, // Optional: delegate each task to subagent
subagentAgent: "default" // Optional: subagent name (default: 'default')
})
Loop Behavior
- Task content is saved to
.ralph/<name>.md - Each iteration: work on task, update file
- Call
ralph_donetool to proceed to next iteration - When complete: output
<promise>COMPLETE</promise> - Loop ends on completion or max iterations (default 50)
User Commands
/ralph start <name|path>- Start a new loop/ralph resume <name>- Resume loop/ralph stop- Pause loop (when agent idle)/ralph-stop- Stop active loop (idle only)/ralph status- Show loops/ralph list --archived- Show archived loops/ralph archive <name>- Move loop to archive/ralph clean [--all]- Clean completed loops/ralph cancel <name>- Delete loop/ralph nuke [--yes]- Delete all .ralph data
During streaming: press ESC to interrupt, send a normal message to resume, and run /ralph-stop when idle to end the loop.
Task File Format
# Task Title
Brief description.
## Goals
- Goal 1
- Goal 2
## Checklist
- [ ] Item 1
- [ ] Item 2
- [x] Completed item
## Notes
(Update with progress, decisions, blockers)
Subagent Mode
Delegate each checklist task to a separate subagent thread:
/ralph start my-tasks --use-subagents --subagent-agent default
How it works:
- Extracts uncompleted checklist items (
- [ ] Task) - Each task is delegated to a fresh subagent thread (1 task = 1 subagent)
- Subagent completes task and marks it done (
- [x] Task) - Main loop orchestrates and tracks progress
- Automatic retry logic for failures (2 attempts)
Benefits:
- Fresh context per task (no pollution)
- Isolated execution (failures don't cascade)
- Clear task tracking and progress reporting
- Suitable for independent, discrete tasks
When to use:
- Tasks are independent (no shared state)
- Each task is substantial enough for separate execution
- You want clean separation between tasks
- Task list is well-defined upfront
Best Practices
- Clear checklist: Break work into discrete items
- Update as you go: Mark items complete, add notes
- Reflect when stuck: Use reflection to reassess approach (normal mode)
- Complete properly: Only output completion marker when truly done
- Subagent mode: Use for independent tasks with clear boundaries
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/zenobi-us/dotfiles/ralph-loop">View ralph-loop on skillZs</a>