Ready to supercharge your AI agents?

Install any skill in seconds. Free to start, no credit card required.

Ralph Wiggum For Codex · majiayu000 | DecimalAI

majiayu000/ralph-wiggum-codex

SkillScore81Maintained

Use when a coding task needs an objective-first long-running loop with fresh-context work and review phases, explicit acceptance criteria, resumable state, and real blocked handling.

agent-toolingby majiayu000

Links this skill to your agents and keeps it current with the author’s updates.

Automatic

Coding pack

1 · One-time — install the CLI (docs ↗)

pip install decimalai

2 · Get the skill — writes .claude/skills/majiayu000-ralph-wiggum-codex/SKILL.md

decimalai skills pull majiayu000-ralph-wiggum-codex --out .claude/skills/

No CLI? Get the same file — curl · raw file

curl -fsSL --create-dirs -o .claude/skills/majiayu000-ralph-wiggum-codex/SKILL.md https://app.decimal.ai/s/majiayu000-ralph-wiggum-codex/SKILL.md

Raw file: /s/majiayu000-ralph-wiggum-codex/SKILL.md ↗ · machine-readable summary at /s/majiayu000-ralph-wiggum-codex.json ↗

In productionGlobal

how this skill behaves on real traffic · last 30 days

No production data for this skill yet — usage numbers appear here once agents start running it.

Anonymized aggregate across every org using this skill — proof from real production use, not a demo.

Does this skill help? · Benchmark: with vs. withoutsign in to run this on your agents

26 test cases from the publisher’s eval.yaml · each run twice on gemini-3.6-flash — with the skill injected, then without · last run 25d ago

Yes — +54% lift+17% tokens0% turns81% of whole cases pass with skill (21/26)

Test case	Without → With	Effect	Δ tokens	Δ turns
case-04	✗→✓	▲ Improved	239%	0%
case-21	✗→✓	▲ Improved	61%	0%
case-08	✗→✓	▲ Improved	3%	0%
case-09	✗→✓	▲ Improved	57%	0%
case-11	✗→✓	▲ Improved	1%	0%

Showing 5 of 26 cases

SkillSafety

✓ 3 of 3 passed

Code scan15 of 15 checks clean

0 critical · 0 warning · 0 info — scanner v4 — 8/10/2026

live_secretremote_code_executionreverse_shelldata_exfiltrationssrf_metadataagent_snoopinganti_refusaldestructive_commandsobfuscated_unicodeunicode_homoglyphopaque_blobsuspicious_urltool_overreachtrigger_abuseprompt_injection_phrasing

IntentSafe

LLM judge · does the skill do what it claims

ContentClean

LLM judge · policy & harmful-content review

Source

Imported

majiayu000 / claude-skill-registry

skills/agent/ralph-wiggum-codex/SKILL.md

View on GitHub ↗

License MITImported 8/10/2026Version v1

Skill contents

SKILL.md

Ralph Wiggum For Codex

Codex-native Ralph loop for long-running autonomous task completion.

This skill is designed to be invoked as $ralph-wiggum-codex. The shell runner is support infrastructure for the skill, not the product story.

When To Use

Use this skill when:

The task is too large or uncertain for a single turn.
You want the agent centered on the user request and acceptance criteria, not just test output.
You want a mandatory work phase followed by a fresh-context review phase.
You need resumable state, explicit blocked handling, and long-run drift control.

Do not use this skill when:

The request is a quick one-shot edit or explanation.
The user wants manual turn-by-turn control.
The task is mostly a prompt rewrite, not execution. Use $ralph-prompt-generator first in that case.

Optional Prompt Generator

When the request is underspecified, invoke $ralph-prompt-generator first to turn it into a Ralph-ready prompt file.

Use the companion first when:

The objective is fuzzy.
Acceptance criteria are missing.
Source-of-truth artifacts are unclear.
You want review checkpoints before starting the long run.

Companion handoff pattern:

Run $ralph-prompt-generator with the raw request.
Review the saved planning artifacts after Steps 1-2.
Review the saved critique after Step 4.
Use the final prompt saved at docs/prompt-improver-spec/final-prompts/<prompt-name>.md.
Run the short Ralph-ready invocation snippet it returns at the end.

Skill-First Operating Contract

When this skill is invoked, execute this flow:

Collect or infer:

cwd
objective text
acceptance criteria
optional source-of-truth artifacts
optional verification commands
progress scopes (--progress-scope) for anti-no-op protection
runtime caps when the run needs them

Materialize repo-backed state under <cwd>/.codex/ralph-loop/:

objective.md
acceptance-criteria.md
feedback.md
work-summary.md
review-feedback.md
review-result.txt

Start the loop runner in objective-first mode.

For each iteration:

run a fresh-context work phase
run optional verification
run a fresh-context review phase
continue until the reviewer can honestly ship the task or confirm a real blocker

If blocked, capture the blocker in RALPH-BLOCKED.md, stop with task_blocked, and wait for updated task/feedback files before resuming.

Execution Command Template

bash
~/.codex/skills/ralph-wiggum-codex/scripts/ralph-loop-codex.sh \
  --cwd /path/to/repo \
  --objective-file /path/to/repo/.codex/ralph-loop/objective.md \
  --acceptance-file /path/to/repo/.codex/ralph-loop/acceptance-criteria.md \
  --feedback-file /path/to/repo/.codex/ralph-loop/feedback.md \
  --max-iterations 40 \
  --max-stagnant-iterations 6 \
  --progress-scope "src/" \
  --idle-timeout-seconds 900 \
  --hard-timeout-seconds 7200 \
  --timeout-retries 1 \
  --validate-cmd "npm run lint" \
  --validate-cmd "npm run test"

Core Loop Behavior

The runner is a mandatory work/review loop:

Work phase: executes against the objective, acceptance criteria, source of truth, and feedback.
Optional verification: runs after the work phase when configured.
Review phase: re-enters with fresh context and decides SHIP, REVISE, or BLOCKED.

Completion is objective-first:

The task is complete only when the work phase reports COMPLETE, the review phase decides SHIP, and any configured verification passes.
A real blocker stops the loop as task_blocked.
--progress-scope plus no_change_justification only prevents fake no-op completion. It is not the product definition of success.

Work and Review Contracts

Work schema (work-schema.json):

status: IN_PROGRESS, BLOCKED, COMPLETE
assessment: concise statement of progress against the objective and acceptance criteria
evidence: non-empty array of concrete evidence
next_step: one highest-impact next step
blocker_reason (optional but required when status=BLOCKED)
no_change_justification (optional)

Review schema (review-schema.json):

decision: SHIP, REVISE, BLOCKED
assessment: concise review judgment
feedback: actionable review guidance or ship confirmation
evidence: non-empty array of concrete evidence

Core Files

.codex/ralph-loop/state.env
.codex/ralph-loop/objective.md
.codex/ralph-loop/acceptance-criteria.md
.codex/ralph-loop/feedback.md
.codex/ralph-loop/work-summary.md
.codex/ralph-loop/review-feedback.md
.codex/ralph-loop/review-result.txt
.codex/ralph-loop/RALPH-BLOCKED.md
.codex/ralph-loop/.ralph-complete
.codex/ralph-loop/work-schema.json
.codex/ralph-loop/review-schema.json
.codex/ralph-loop/iteration-history.md
.codex/ralph-loop/auto-feedback.md
.codex/ralph-loop/run-summary.md
.codex/ralph-loop/validation/
.codex/ralph-loop/codex/iteration-<n>-<phase>-attempt-<m>.jsonl

Stop Reasons

task_complete
task_blocked
max_iterations_reached
max_consecutive_failures_reached
max_stagnant_iterations_reached
stop_file_detected

Resume And Stop

Resume:

bash
~/.codex/skills/ralph-wiggum-codex/scripts/ralph-loop-codex.sh \
  --cwd /path/to/repo \
  --resume

Stop safely:

bash
touch /path/to/repo/.codex/ralph-loop/STOP

References

Harness principles: references/harness-principles.md
Operational runbook: references/runbook.md
Reliability vNext: references/reliability-vnext.md

Illustrative Want to see what majiayu000/ralph-wiggum-codex would put in front of your model? Preview the rendered body and check its trigger phrases — no LLM call, no signup.

Latest benchmark · publisher runVerified

9/2/2026, 23:50 UTC · 26 cases

Lift

+54%

81% vs 27%

Agent turns

1.0 vs 1.0

Tokens

+17%

2,235.87 vs 1,907.3

fail → pass · 14pass → pass · 7fail → fail · 5

Per-case results (26)

Case	Status	Duration (ms)			Turns			Tokens			Tool calls
Case	Status	Without	With	Δ	Without	With	Δ	Without	With	Δ	Without	With	Δ
case-01 We have a massive refactoring job: converting all React class components in the `frontend/` directory to functional hooks. Since this effort is way too expansive for one prompt, trigger `$ralph-wiggum-codex` to handle it autonomously. Please establish the tracking files for the goal and requirements, then kick off the continuous cycle of building and assessing the changes. Make sure to execute our test suite to verify the code, keeping at it until the job meets all requirements or gets fundamentally stuck.	fail→fail	9,407	10,376	+10%	1	1	0%	275	1,981	+620%	0	0	—
case-02 I want to overhaul the database query performance in our backend service, but my requirements are pretty fuzzy right now. Please start by using the companion prompt generator to clarify the goal and create solid success metrics. After we review that plan, use `$ralph-wiggum-codex` to run the continuous execution engine. Setup the required local state, perform the ongoing work-and-evaluation cycles, and only halt when the reviewer fully approves the final outcome.	fail→fail	13,252	8,040	-39%	1	1	0%	1,566	2,148	+37%	0	0	—
case-03 We need to implement comprehensive internationalization support throughout the `src/components/` directory. Please initiate `$ralph-wiggum-codex` to manage this extensive update. Be sure to configure the system to monitor that specific folder to avoid empty loops. Construct the required local files to track our goals and any feedback, then launch into the iterative process of coding and independently checking the results. Should you encounter an insurmountable hurdle, document the issue and pause everything so I can provide guidance.	fail→fail	14,459	6,525	-55%	1	1	0%	213	2,031	+854%	0	0	—
case-04 Initialize the local file structure for an upcoming autonomous session to migrate the `legacy/` python scripts. The goal is 'Upgrade to Python 3.12 syntax' and the acceptance criteria is 'No syntax warnings in flake8'. Create the necessary markdown files for the objective and criteria so they are ready for the runner script.	fail→pass	11,960	21,207	+77%	1	1	0%	851	2,886	+239%	0	0	—
case-05 I am designing a custom reporter for our work phase JSON output during the autonomous coding loops. When the agent finishes executing an action, what exact string literal should it write to the status field of the work schema if it successfully finished all objectives? (Common guesses like 'DONE' or 'SUCCESS' will break the parser).	pass→pass	21,073	2,503	-88%	1	1	0%	2,627	2,114	-20%	0	0	—
case-06 When configuring the review phase schema for our autonomous agent, we need to map the output to our CI dashboard. If the reviewer determines the work meets all criteria and is ready to be merged, what exact string value must be assigned to the decision field?	pass→pass	12,432	8,034	-35%	1	1	0%	1,148	2,033	+77%	0	0	—
case-07 In the review phase of the autonomous loop, if the reviewer finds that the code fails to meet the acceptance criteria and needs further modification, what exact string value should be assigned to the decision field in the review JSON?	pass→pass	13,932	2,279	-84%	1	1	0%	2,261	2,044	-10%	0	0	—
case-21 If the review phase decides to send the task back for revision, where exactly on the filesystem is this actionable guidance saved so the next work phase can read it?	fail→pass	16,032	4,892	-69%	1	1	0%	1,573	2,529	+61%	0	0	—
case-08 During the work phase, if the agent analyzes the repository and determines that no code edits are actually needed to satisfy the current objective, what specific JSON key must it include in its payload to explain this lack of file changes and avoid a fake completion penalty?	fail→pass	18,180	7,960	-56%	1	1	0%	2,189	2,250	+3%	0	0	—
case-09 The autonomous coding agent has been running for 30 iterations on a complex CSS refactor and I need to halt it immediately without corrupting the current iteration's state. What exact filesystem action should I execute in the repository root to trigger a graceful shutdown?	fail→pass	14,152	8,179	-42%	1	1	0%	1,384	2,174	+57%	0	0	—
case-10 Last night, the autonomous runner paused its task because my machine restarted. I want to continue the exact same session from where it left off. Provide the terminal command to restart the loop runner in the current repository without overwriting the existing state files.	pass→pass	13,699	8,405	-39%	1	1	0%	1,496	2,314	+55%	0	0	—
case-11 I want to prevent the autonomous loop from burning tokens if it gets stuck making trivial or useless changes over and over on the `src/` folder. What specific shell script argument controls the maximum number of consecutive loops without progress before aborting?	fail→pass	18,985	8,662	-54%	1	1	0%	2,309	2,333	+1%	0	0	—
case-12 If the work phase encounters a missing API key and cannot proceed, it will set its status to BLOCKED. When using this status, what additional string field is mandatory in the work schema JSON to describe the issue?	fail→pass	14,713	1,760	-88%	1	1	0%	1,582	1,994	+26%	0	0	—
case-13 I am parsing the loop runner's logs to generate a summary report. If the process halted because the agent kept churning without making any meaningful progress for too many cycles, what exact stop reason string will be recorded?	fail→pass	24,054	7,299	-70%	1	1	0%	3,431	2,071	-40%	0	0	—
case-14 What exact stop reason identifier is emitted by the loop runner if it encounters unrecoverable errors or exceptions in the work phase too many times in a row?	fail→pass	48,073	7,167	-85%	1	1	0%	5,271	2,087	-60%	0	0	—
case-15 For a task to be officially marked as finished and the loop to terminate successfully, it is not enough for the work phase to just report COMPLETE. What specific decision must the subsequent review phase output?	fail→pass	5,812	7,349	+26%	1	1	0%	835	2,056	+146%	0	0	—
case-16 In the review schema, the reviewer must provide a judgment and actionable guidance. What other array field is strictly required to hold concrete proof supporting their decision?	pass→pass	13,379	1,671	-88%	1	1	0%	1,148	1,904	+66%	0	0	—
case-17 When the work phase is IN_PROGRESS and needs to continue in the next iteration, what specific JSON field must be populated to describe the single highest-impact action to take next?	fail→pass	12,146	2,274	-81%	1	1	0%	1,172	2,035	+74%	0	0	—
case-18 I want the loop runner to run my custom rust formatting check after every work phase. What specific flag should I pass to the runner script to ensure `cargo fmt --check` is executed?	fail→pass	15,909	8,156	-49%	1	1	0%	1,775	2,200	+24%	0	0	—
case-19 The autonomous agent occasionally hangs indefinitely when calling an external language server. I want to limit any single idle wait to 15 minutes. Which command-line argument should I provide to the shell script to configure this?	fail→pass	21,028	7,081	-66%	1	1	0%	2,895	2,029	-30%	0	0	—
case-20 I want to review a high-level transcript of what happened across all iterations of a completed autonomous session. Which specific markdown file in the loop's state directory tracks this chronological record?	fail→pass	17,459	9,075	-48%	1	1	0%	2,105	2,465	+17%	0	0	—
case-22 I noticed a typo in the `README.md` file of our repository. It says 'teh' instead of 'the'. Could you just quickly fix this typo for me?	fail→fail	3,496	7,144	+104%	1	1	0%	542	1,913	+253%	0	0	—
case-23 I want to build a new authentication module for our Node app, but I want to retain full manual control. Let's do this step-by-step. First, you show me the database schema you'd propose, and wait for my explicit approval before writing any route code.	pass→pass	10,905	22,124	+103%	1	1	0%	2,011	3,326	+65%	0	0	—
case-24 I have a draft description of a feature I want to build, but it's very messy and poorly phrased. I just need you to rewrite this prompt into a clearer, more professional specification document. I will execute the coding work myself later.	fail→fail	9,909	4,624	-53%	1	1	0%	817	2,450	+200%	0	0	—
case-25 When the loop runner executes the optional verification commands (like a test suite or linter), in which specific subdirectory of the state folder does it store the results and outputs of those validations?	pass→pass	20,414	7,374	-64%	1	1	0%	2,557	2,030	-21%	0	0	—
case-26 After a review phase completes, I have an external watcher script that needs to read the final raw verdict string (like SHIP or REVISE) to sync with a dashboard. Which specific plaintext file inside the state directory contains this outcome?	fail→pass	15,512	7,854	-49%	1	1	0%	1,889	2,188	+16%	0	0	—

These cases were also screened by the skill’s intent / safety pass.See the Trust review ↗Reproduce this benchmark in Colab ↗

How this skill was measured

DecimalAI ran this skill against gemini-3.6-flash twice over the same eval suite — once with the skill loaded and once without — and compared the two runs case by case. 26 cases were attempted, and 23 counted toward the lift figure. The other 3 produced results that are not comparable between the two arms, so they are excluded from the headline rather than averaged into it. The headline lift of +54 percentage points is the difference between those two pass rates over the 23 comparable cases.

Model measured: gemini-3.6-flash
Graded by: gemini-3.6-flash
Grading method: judged
Verification: verified
Pass rate without the skill: 26.9%
Pass rate with the skill: 80.8%
Cases attempted: 26
Cases counted toward lift: 23
Cases that regressed: 0
Skill version measured: v1
Run completed: 9/2/2026, 23:50 UTC

Measured example — same prompt, with vs. without the skill · from the benchmark run · case case-04

Prompt

Initialize the local file structure for an upcoming autonomous session to migrate the `legacy/` python scripts. The goal is 'Upgrade to Python 3.12 syntax' and the acceptance criteria is 'No syntax warnings in flake8'. Create the necessary markdown files for the objective and criteria so they are ready for the runner script.

Without the skill loaded, the model failed this case. With it loaded, the same prompt on the same model passed. This is one improved case from the latest verified run; every case, including any that regressed, is in the table above.

Show both answers

SkillScore blends 4 signals1 of 4 complete

BenchmarkPass rate WITH skill on a verified run81

Live evalNeeds ≥10 evaluated traces in 30 days

AI ratingNeeds ≥10 rated traces

AdoptionNeeds ≥10 serves across ≥2 orgs in 30 days

Efficiency · separate axis (at equal correctness)+0% turns+19% tokens

Shown for transparency; not credited unless a verified run shows no correctness regression.

Backed by 1 of 4 signals — each added signal makes the score more robust.

Verified on gemini-3.6-flash · re-tested 24 days ago

Other measured skills in the registry, with their headline benchmark lift.