skill CX Codex

ralph-loop — Claude Code skill: iterate until the task is done

Q: How do I install ralph-loop in Claude Code?

Run `npx skills add cursor/plugins --skill ralph-loop -a claude-code`. The skill lands at `~/.claude/skills/ralph-loop/SKILL.md`.

Q: What does ralph-loop do?

It creates `.cursor/ralph/scratchpad.md` holding your prompt and loop settings, then a stop hook returns that prompt at the end of every turn until the stop condition fires or the iteration limit runs out.

Q: How does the loop know when to stop?

Through `completion_promise`: the agent emits `TEXT` only once the condition is truly satisfied. False promises to break out are off limits, and `max_iterations` acts as a backstop.

A skill that keeps feeding the same prompt back to the agent after every turn, so each pass builds on the previous one.

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓

npx skills add cursor/plugins --skill ralph-loop -a claude-code

Open on GitHub

What ralph-loop does

Ralph Loop turns a single request into a repeating cycle. When a turn ends, the agent gets the same prompt again and can read what it produced last time, so work continues instead of restarting. Useful for tasks too large to finish in one pass.

The skill writes a state file at .cursor/ralph/scratchpad.md, creating the .cursor/ralph/ directory first. Its YAML header holds the iteration number, max_iterations, and completion_promise; your task prompt sits underneath. A stop hook does the looping: it catches the end of each turn and re-sends the prompt as a followup message tagged [Ralph loop iteration N.].

max_iterations defaults to 0, which means no cap. The skill recommends setting a limit anyway as a safety net. The only clean way out is <promise>TEXT</promise>, and it should appear when the condition is genuinely met — not as an escape hatch. Put the completion_promise value in quotes if it contains special characters.

What it helps with

push a large task through many agent passes to completion
keep context across iterations of the same job
define a stop condition instead of looping forever
cap the number of iterations so the agent does not spin
run unattended refinement from one prompt

Example prompts for the agent

Start a ralph loop to build a REST API for todos with CRUD, validation and tests, max 20 iterations, completion promise COMPLETE
Run a ralph loop on the payments module refactor with no iteration limit
Start an iterative loop to fix the failing tests in tests/api, stop on promise DONE

How to install ralph-loop

1Skills CLI (Vercel)

npx skills add cursor/plugins --skill ralph-loop -a claude-code

2Manually: put the files in place

~/.claude/skills/ralph-loop/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/ralph-loop/

1Skills CLI (Vercel)

npx skills add cursor/plugins --skill ralph-loop -a codex

2Manually: put the files in place

.agents/skills/ralph-loop/SKILL.md

For all projects use ~/.agents/skills/

1Skills CLI (Vercel)

npx skills add cursor/plugins --skill ralph-loop -a cursor

2Manually: put the files in place

.cursor/skills/ralph-loop/SKILL.md

Cursor also reads .agents/skills/ and .claude/skills/

1GitHub CLI

gh skill install cursor/plugins ralph-loop

2Manually: put the files in place

.github/skills/ralph-loop/SKILL.md

1Skills CLI (Vercel)

npx skills add cursor/plugins --skill ralph-loop -a gemini-cli

2Platform CLI

gemini skills install https://github.com/cursor/plugins --path ralph-loop/skills/ralph-loop

Manually: put the files in place

.devin/skills/ralph-loop/SKILL.md

The legacy .windsurf/skills/ path still works

Skills CLI (Vercel)

npx skills add cursor/plugins --skill ralph-loop -a opencode

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about ralph-loop

How do I install ralph-loop in Claude Code?

Run npx skills add cursor/plugins --skill ralph-loop -a claude-code. The skill lands at ~/.claude/skills/ralph-loop/SKILL.md.

What does ralph-loop do?

It creates .cursor/ralph/scratchpad.md holding your prompt and loop settings, then a stop hook returns that prompt at the end of every turn until the stop condition fires or the iteration limit runs out.

How does the loop know when to stop?

Through completion_promise: the agent emits <promise>TEXT</promise> only once the condition is truly satisfied. False promises to break out are off limits, and max_iterations acts as a backstop.

setup-matt-pocock-skills Matt Pocock This skill configures a repository for Matt Pocock's engineering skills by setting its issue tracker, triage labels, and domain docs layout. Run it before using the other skills. 1,052,851installs ask-matt Matt Pocock Routes you to the right Matt Pocock skill or flow for the task at hand. Use it when you need a starting point for a feature, prototype, incoming issue, or hard bug. 766,587installs to-tickets Matt Pocock Turns a plan, spec, or conversation into small end-to-end tickets with explicit blockers. Use it to agree on the work breakdown before tickets go to a tracker. 711,230installs writing-plans Jesse Vincent This skill turns requirements for a multi-step task into an implementation plan before code changes begin. It helps when another engineer needs exact files, interfaces, and checks. CX Codex 282,859installs caveman-review JuliusBrussee Turns code review comments into one line per finding: location, problem, fix. Useful when a diff or PR needs a fast pass without the filler. CX Codex +1 411,800installs caveman-compress JuliusBrussee Compresses CLAUDE.md, todo lists, and other prose files into a shorter format while retaining a readable backup. CX Codex +1 411,500installs

From the same set47

create-plugin-scaffold Builds a Cursor plugin scaffold: manifest, component folders and a marketplace entry. Handy when a plugin starts from an empty folder. CX Codex +1 1,200installs docs-canvas Turns architecture notes, API specs, and walkthroughs into an interactive Cursor Canvas with navigation and diagram cards. CX Codex +1 1,200installs orchestrate This skill splits a large goal across parallel Cursor cloud agents and gathers their handoffs. It runs only when the user explicitly calls /orchestrate. CX Codex +1 1,200installs cursor-sdk A skill for anyone driving Cursor agents from TypeScript: which call shape to use, local or cloud runtime, and where errors come from. CX Codex +1 1,200installs create-learning-path A skill that turns a topic into a study plan with milestones, timed checkpoints and practice exercises. CX Codex +1 977installs run-learning-retrospective This skill runs a learning retrospective: checks finished work against goals, finds recurring blockers and adjusts the plan. Handy after a milestone closes. CX Codex +1 902installs cancel-ralph Aborts an active Ralph loop and cleans up its state files. Useful when an agent gets stuck or you need to halt the loop manually. CX Codex +1 901installs ralph-loop-help A skill that answers questions about the Ralph Loop technique: how the cycle runs, which options exist, and when to reach for it. CX Codex +1 899installs