Guide · Agent skill

How to use the Ultragoal multi-goal workflow agent skill

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Ultragoal is an agent skill that helps an AI coding agent break a large project into an ordered list of goals and record progress in an append-only ledger stored in your repository under .omc/ultragoal. It is for developers running long, multi-step work across several Claude Code sessions or git worktrees. By the end of this guide you will know what the skill does, how to install it, how to trigger it, and where its limits are, including the fact that it cannot set Claude's native /goal on its own.

Ultragoal Multi-Goal WorkflowYeachan-Heo/oh-my-claudecode · MIT Download the skill

Quick start

1Install the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/, or upload it under Settings → Capabilities → Skills in the Claude apps.
2Confirm the omc command. Make sure oh-my-claudecode is installed with omc on your PATH, or use node bin/oh-my-claudecode.js for a plugin-only install.
3Create the plan. Run omc ultragoal create-goals with --brief-file or explicit --goal entries. Add --plan-id if several sessions will run at once.
4Start the first story. Run omc ultragoal complete-goals. Read the handoff it prints and ask the user to type the /goal command it gives you.
5Work and checkpoint. Complete the story, then run checkpoint with its goal id, status, evidence and a /goal snapshot.
6Gate the final story. For the last story, pass quality gate evidence for aiSlopCleaner, verification and codeReview. If review is not clean, record blockers instead.
7Check status. Run omc ultragoal status at any point to see where the run stands.

What the ultragoal skill makes the agent do

Ultragoal takes a brief and splits it into an ordered set of goals. As work proceeds, it records start, checkpoint, blocker and failure events in a durable ledger, so the state of the project survives a session restart or a fresh worktree.

The skill also coordinates with Claude Code's /goal slash command. /goal is a session-scoped stop hook that keeps the session from ending until a condition holds. Ultragoal adds a durable plan, ledger and gating layer on top of it. Final completion can be gated behind ai-slop-cleaner, verification and $code-review.

Writes plan and ledger artifacts under .omc/ultragoal in the repository
Tracks attempt counts and per-story evidence
Prints handoff text that tells the active Claude agent how to drive /goal
Records review blockers as new stories instead of marking unfinished work complete

Install the ultragoal skill

The skill ships as a ZIP file from the download link on this page. You can install it in one of two ways.

For Claude Code, unzip the download into ~/.claude/skills/ to make it available for all your projects, or into a project's .claude/skills/ folder to limit it to that project. For the Claude apps, upload the ZIP under Settings → Capabilities → Skills.

The skill's package contains a single file, SKILL.md. The skill is built on oh-my-claudecode (MIT licence), so the omc command or a plugin-only install is needed to run its commands.

Personal install: unzip into ~/.claude/skills/
Project install: unzip into the project's .claude/skills/
Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Check the requirements before you start

Ultragoal needs oh-my-claudecode installed with the omc command available on your PATH. If you installed only the plugin, there is no omc command, so use the node bin/oh-my-claudecode.js entry point instead. Claude Code is needed for the /goal slash command workflow, and the skill expects a Git repository for its workspace state.

The skill runs scripts but does not use the network, according to its description.

oh-my-claudecode with omc on PATH, or node <plugin-root>/bin/oh-my-claudecode.js for plugin-only installs
Claude Code for the /goal workflow
A Git repository for workspace state

omc ultragoal status

Trigger the skill with a natural request

You do not need to memorise commands to start. Ask the agent for a durable, multi-session plan for a large initiative, and mention that the work should be tracked across sessions or worktrees. The skill is a good fit when the work has several ordered stories with evidence to collect for each.

Ultragoal also accepts an argument hint of <brief or subcommand>, so you can pass a brief or a specific subcommand directly.

"Break the database migration into ordered goals I can resume across sessions."
"Track this multi-repo rollout with ultragoal so parallel sessions don't clobber each other."
"Plan this large refactor as an ultragoal with a final review gate."

Create a plan and start a story

Create a plan from a brief file, or pass the stories explicitly. The default mode is aggregate, where one Claude /goal covers the whole run. Use --claude-goal-mode per-story if each story should have its own /goal.

Then start or resume the next story with complete-goals. With no goal id it resumes the active story or starts the first pending one. When it prints the handoff, the active agent must ask you to type the /goal command, because neither the shell nor the agent can set it in standalone Claude Code. Wait for you to confirm before working the story.

Plan from a file: create-goals --brief-file plan.md
Plan with explicit stories: create-goals --brief with one or more --goal entries in the form Title::Objective
Start or resume: complete-goals, optionally with a goal id

omc ultragoal create-goals --brief-file plan.md
omc ultragoal create-goals --brief "ship the migration" \
  --goal "Schema::Add new columns" \
  --goal "Backfill::Backfill rows in batches" \
  --goal "Cutover::Drop old columns and switch reads"
omc ultragoal complete-goals

Checkpoint stories and handle review blockers

When a story is complete, checkpoint it with its status, evidence and a snapshot of the active /goal state. The final story also needs a quality gate covering aiSlopCleaner, verification and codeReview evidence, all clean.

If the final review is not clean, do not mark the story complete. Record blockers instead. This appends a new blocker story and keeps the Claude /goal active. Use omc ultragoal status at any time to inspect state.

Checkpoint with --goal-id, --status, --evidence and --claude-goal-json
For the final story, add --quality-gate-json
Record review blockers with record-review-blockers rather than forcing completion

omc ultragoal checkpoint --goal-id G001-... --status complete \
  --evidence "tests/files/PR evidence" \
  --claude-goal-json '{"goal":{"objective":"...","status":"active"}}'

Run parallel sessions with plan IDs

When several Claude sessions in the same workspace run ultragoal at the same time, give each run its own plan. Pass --plan-id with a stable id, or --auto-plan-id, which derives an id from the brief title. Then pass the same --plan-id to every later subcommand in that session. Without this, two sessions creating goals would overwrite each other's plan.

For multi-repo workspaces, the source suggests placing a .omc-workspace marker in the parent directory so sub-repos share one .omc/ folder. Use omc ultragoal list-plans to see available plan IDs.

--plan-id <stable-id> or --auto-plan-id when creating goals
Plans are written to .omc/ultragoal/plans/{planId}/
Resolution order for state location: OMC_STATE_DIR, then .omc-workspace, then git, then the current directory

What people use it for

Splitting a multi-stage database migration into schema, backfill and cutover stories, each with its own evidence.
Running the same initiative in parallel across several sub-repos, with each session on a separate plan id.
Resuming a long refactor in a fresh worktree after the original Claude session has ended.
Gating a large feature's completion behind cleanup, verification and code review.

Frequently asked questions

How do I install the ultragoal skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder for one project. In the Claude apps, upload the ZIP under Settings → Capabilities → Skills.

What does the ultragoal skill require?

It needs oh-my-claudecode installed with the omc command on your PATH, or the node bin/oh-my-claudecode.js entry point for plugin-only installs. Claude Code is needed for the /goal workflow, and a Git repository is expected for workspace state.

Is ultragoal free to use?

The skill is published under the MIT licence. This page does not list pricing, so check the source repository for any terms beyond the licence.

Can ultragoal set Claude's /goal for me?

No. The skill cannot set or change /goal from the shell. It prints handoff instructions, and the active agent must ask you to type the /goal command in the session. Snapshots it receives are model-supplied and do not count as an active /goal for the PreToolUse guard.

When should I use a different skill instead of ultragoal?

For a single small change, use direct delegation or ralph, since ultragoal adds overhead. For planning with no execution loop, use plan.

Why does my second Claude session overwrite the plan?

Two sessions creating goals in the same workspace share the default plan path. Pass --plan-id with a stable id or --auto-plan-id so each run writes to its own .omc/ultragoal/plans/{planId}/ folder, and pass the same id to every later subcommand.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use ultragoal if you run long, multi-step initiatives across several Claude Code sessions, worktrees or repos and want completion gated behind review. Skip it for small changes or planning-only work, and do not expect it to control Claude's /goal state; you will still need to type the /goal command yourself.

Download the skill