octopus-skill

What It Does

octopus is a Markdown-only agent skill and prompt library for long-horizon agent work: multi-hour coding sessions, multi-milestone migrations, and a queue of long tasks (related or unrelated) that outlive a single context window. It targets developers running agents in Claude Code, Codex, Cursor, or Grok. The skill's single job is to compile a vague request into a small, durable graph of agent nodes that stay on-spec across many rounds, then optionally launch those nodes on the host. It calls this "graph engineering": specialized roles connected through inspectable files rather than a shared, drifting context.

The graph has three roles. The executor node drives the work one ledger item at a time, verifies it in the same round, and records the result. The supervisor node boots fresh every tick from a clean context, independently re-verifies the executor's claimed-done work against the real acceptance bar, checkpoint-commits only what passes its audit, and corrects drift through a one-way directives file. An optional scout node researches a bounded question off the critical path. All load-bearing state lives on disk under .octopus// (a ledger, a directives queue, an ops file, and archive shards), which is what makes a run portable: you can switch hosts mid-run by re-sending the same frozen prompt against the same files. Crucially, it is a prompt library, not a runtime: there is no application server, no framework dependency, and no vendor lock-in.

The Good

The methodology is the most rigorously argued design GearScope has reviewed, and each rule maps to a specific, named failure mode. The lib/methodology.md file defines 10 rules, and every one states what it prevents before how to apply it. Rule 8 (clean-context supervisor separation) is the load-bearing one and the document says so plainly: "A single agent grinding a long task is a loop... it cannot audit its own drift, because the audit runs in the drifted context." The fix is structural, not behavioral: the supervisor is a different node with a fresh context that re-runs the gates and inspects the real diff, rather than trusting the ledger's word for "done". The docs/model.md file then formalizes this into a typed-edge vocabulary (state edges vs. signal edges, single-writer invariants, a node tuple of prompt, model, activation, read-set, write-set, authority, stop-condition) and shows, in a table, how three earlier proposals (an auditor node, a gates.md edge, the scout node) either collapsed into existing constructs or earned their place. That kind of "does a new abstraction collapse into an existing one?" discipline is rare in prompt libraries, which usually accumulate instructions rather than reason about them.

The convergence forcing function is encoded as durable state, not a recomputed count, which fixes the exact reason such rules silently fail. Rule 3 requires periodic zero-growth rounds (delete dead code, merge duplication, tighten interfaces). The failure mode it names is precise: on a host where each round is a fresh, stateless context, a cheap model focused on its item will not reliably recompute "round mod 5" every time, so the convergence round that was supposed to fire simply does not. The fix is to put a convergence tracker (rounds-since, net-lines-since, a "next round converges" flag) directly in the ledger's status header, which the executor checks first thing each round, and to key it to real accumulated bloat (a 400-line net cap) not only a blind count. The clean-context supervisor then audits that a flagged convergence round converged. The ledger template (templates/ledger.md) and executor template (templates/executor.md) both carry this tracker, which I confirmed by grep. This is the difference between a rule an agent is told to follow and a rule the run's structure enforces.

The owner-decision contract is a concrete, reusable UX pattern, not a vague "ask the user". Both the executor and supervisor templates ship an exact decision-card format: a plain-language sentence, a "why now" line on what is blocked, a labeled recommendation, at most three mutually exclusive A/B/C outcomes with tradeoffs, and a "reply with A/B/C" instruction. The methodology forbids ending with "what do you think?" or making the owner invent option D, and if no answer arrives, the run stays parked at the safe no-change state. There is a deeper idea here too: a decision that sits on the goal's own critical path (the goal is dropping dead tables, so every round hits a DDL) is pre-adjudicated in the interview into a standing authorization with an objective evidence bar ("drop once 0 rows plus 0 consumers plus 0 reads/writes, via reversible migration"), so the executor acts autonomously and the owner retro-reviews. Only a decision that cannot be written as a bar in advance stays blocking. This is one of the better answers to the "agent stalls waiting on a human" problem I have seen.

Install and structural validation are clean and verified, including a strict Claude Code plugin check. claude plugin validate . --strict passed with no warnings. Both manifests (.claude-plugin/plugin.json and marketplace.json) are valid JSON. All 56 relative cross-file markdown links across the 8 core docs resolve to real files. Both SKILL.md files (the /octopus fit-check entrypoint and the loop-graph authoring skill) carry name and description frontmatter. All 8 runtime templates (executor, ledger, directives, supervisor, handoff, scout, findings, ops-and-environment) are present. The install.sh installer ran in an isolated HOME, symlinks the whole repo as a single octopus skill into both the Codex and Cursor skill directories, resolves to a reachable SKILL.md through the link, and is idempotent (the re-run detected the existing clone and pulled). The plugin version field is intentionally omitted so Claude Code uses the git SHA and users auto-update on every push, a documented and defensible choice spelled out in AGENTS.md.

The worked examples are internally coherent and demonstrate the rules, not just describe them. The add-tests-to-cli example ledger runs three rounds against a fictional taskcat date parser, and it shows the register-then-defer rule in action: Round 1 finds an ambiguous same-weekday case and logs it as GAP-001 rather than fixing it on the side; Round 2 reproduces a timezone off-by-one as an xfail and logs GAP-002 without fixing it; Round 3 fixes GAP-002. The convergence tracker, gate scoreboard, and debt register all update consistently across the rounds. The migrate-blob-storage example is the longer one, with milestones, a cohort pilot, and a non-skippable milestone gate that blocks until the supervisor audits and releases. These are the kind of examples that prove a prompt library was mined from real runs rather than written on a whiteboard.

The Bad

The marquee same-host auto-launch path requires bleeding-edge host features most real users will not have configured, so it often degrades to copy-paste prompts. The "create both nodes here" mode (the path that actually starts an executor and a supervisor without manual setup) needs all of the following on Claude Code: version 2.1.143 or later, background sessions and the agent view enabled (claude agents --json works), /loop and cron tools enabled, and a trusted workspace. On Codex it needs project-task and Scheduled-task actions. The skill handles this correctly (it runs the capability checks, explains the single blocker if one fails, and falls back to filled prompts), but the practical reality is that the feature that distinguishes octopus from "a good multi-agent prompt" is gated behind host configuration that many users have not turned on. For Cursor, Grok, and shell/cron, direct launch is not supported at all, only prompts-only execution.

There is no native install path for Hermes Agent or OpenClaw, despite the broader agent-skills ecosystem. The install.sh only symlinks into $HOME/.codex/skills and $HOME/.cursor/skills, and the Claude Code path is the plugin marketplace. Grok and shell/cron are prompts-only targets with their own reference files. A Hermes user can manually symlink the repo into ~/.hermes/skills/octopus (I confirmed the root SKILL.md and its delegated skills/loop-graph/SKILL.md resolve through such a link), but this is undocumented. The host reference set (Codex, Claude Code, Grok, Cursor, shell/cron) is Claude-Code-and-Codex-centric, which is understandable for a young repo but narrows the fit for the wider multi-host skills ecosystem.

The complexity ceiling is real, and the skill itself warns that most tasks should not use it. The full model asks a user to internalize roughly 10 rules, a node/edge vocabulary, a convergence tracker, a milestone-gate state machine, a gate-wait backlog protocol with disjoint write sets, a findings-edge pointer convention, and a directives watermark. The README and both SKILL.md files repeatedly say "if you do not need the graph, do not use octopus" and route one-shot, PR-sized, single-session tasks back to the host's ordinary task or goal. That honesty is correct, but it means the skill deliberately excludes the majority of daily coding work, and the value concentrates on the long-horizon, multi-milestone niche where a misapplied rule (for example, a convergence round that deletes code someone still needs, or a misjudged gate-wait write set) has a higher blast radius than a simpler approach.

There is no test suite, no CI, a single author, and the repo is 12 days old, so maturity is low even though the design is mature. The AGENTS.md file states plainly under "Checks": "there is no test suite." The contribution checks are manual (run claude plugin validate ., re-read the examples for coherence). There is a single git tag (v0.2.0) and a single contributor. The plugin version is intentionally unpinned (git-SHA auto-update), which maximizes freshness but gives a consumer no stability guarantee: a push that changes a template's invariants updates every installed copy on the next load. None of this is unusual for a 12-day-old repo with 39 stars, and the design quality is far ahead of its age, but an operator depending on it for real long-horizon runs is adopting an early, single-maintainer, unpinned library.

Smoke Test Results

Tested on the host (macOS, aarch64, Claude Code 2.1.152 available) against a fresh clone of levi-qiao/octopus-skill. Because this is a doc-only Markdown prompt library with one 51-line POSIX shell installer and no application code, the smoke test is structural validation plus a functional installer run rather than a sandboxed dependency install.

Run A. Structural validation (frontmatter, manifests, links)

$ python3 validate.py
.claude-plugin/plugin.json: VALID JSON
.claude-plugin/marketplace.json: VALID JSON
Checked 56 relative links across 8 docs -> 0 broken
./SKILL.md: name=yes desc=yes
./skills/loop-graph/SKILL.md: name=yes desc=yes
template executor.md: present (138 lines)
template ledger.md: present (115 lines)
... (6 more templates present)
=== RESULT === ALL CHECKS PASS (2 "placeholder" hits are prose instructions, not real gaps)

Pass rate: structural checks all green. No broken cross-references, valid manifests, correct frontmatter on every SKILL.md.

Full validation log →

Run B. Claude Code plugin validation (the canonical install check)

$ claude plugin validate . --strict
Validating marketplace manifest: .claude-plugin/marketplace.json
✔ Validation passed
$ sh -n install.sh # syntax
# (clean)

Pass rate: strict plugin validation passes. This is the badge-worthy result: the official Claude Code validator accepts the marketplace manifest under --strict with zero warnings, and the installer passes shell syntax checks.

Full sandbox log →

Run C. Functional verification (installer behavior + invariant self-consistency)

$ python3 functional_test.py
[PASS] install.sh exits 0: rc=0
[PASS] install.sh symlinks octopus for Codex
[PASS] install.sh symlinks octopus for Cursor
[PASS] linked SKILL.md reachable through symlink
[PASS] install.sh idempotent (re-run detects existing clone, pulls)
[PASS] Hermes skill dir has SKILL.md (manual symlink)
[PASS] delegated loop-graph SKILL.md resolves
[PASS] lib/methodology.md resolves (shared ref)
[PASS] supervisor template forbids ledger writes
[PASS] supervisor template writes directives only
[PASS] ledger has convergence tracker
[PASS] executor references convergence tracker
[PASS] executor has red lines section
[PASS] example 1 ledger present + has rounds
[PASS] example 1 executor present
[PASS] example 2 ledger present (multi-milestone)
[PASS] bilingual README section-count parity. EN=13 ZH=13
=== FUNCTIONAL SUMMARY === 18/18 checks passed

Functional pass rate: 18 of 18. The installer works and is idempotent, the model's invariants (single-writer ledger, clean-context supervisor, convergence tracker) are present in the templates, and the examples are coherent.

What the runs tell you

The structure, install, and plugin surfaces are verified clean: a user who runs install.sh or /plugin marketplace add gets a working, validated skill with no broken references. What is not verified is the core long-horizon claim itself, because proving that the clean-context supervisor actually catches drift an executor hides requires a live multi-hour run on a configured Claude Code or Codex host against a genuine long task. The design argues the case convincingly and the templates enforce the invariants, but the execution-level proof is out of reach of a desk and install test.

Setup Walkthrough

1. Claude Code (recommended): /plugin marketplace add levi-qiao/octopus-skill, then /plugin install octopus@octopus-skill. Invoke /octopus to start.
2. Codex or Cursor: curl -fsSL https://raw.githubusercontent.com/levi-qiao/octopus-skill/main/install.sh | sh. This clones the library once to ~/.local/share/octopus-skill and symlinks it into ~/.codex/skills and ~/.cursor/skills as a single octopus skill. Invoke /octopus.
3. Design a run: Invoke /octopus. It detects the host, inspects the workspace, asks at most three unresolved owner questions, and compiles the run into .octopus//. Choose direct creation (Codex or Claude Code, if capabilities pass) to start both nodes, or prompts-only for manual or cross-host launch.

One gotcha: Claude Code does not load symlinked skill directories, which is exactly why the installer skips it and routes you to the plugin path. The installer prints this reminder. A second gotcha: the direct-launch path needs /loop, cron, and background sessions enabled on Claude Code 2.1.143+, so if those are off, expect the prompts-only handoff rather than auto-started nodes.

Alternatives

1. The host's ordinary task or goal - for any self-contained job that fits one session. octopus's own fit check will tell you to use this, and it is the right default for the majority of work.
2. LangGraph / CrewAI / AutoGen - if you need a real runtime with programmatic orchestration, state machines, and a deployment stack rather than a Markdown prompt library. Heavier, framework-bound, but more expressive for complex pipelines.
3. A single well-structured mega-prompt - for tasks that need a long push but lack the drift, fake-done, or host-switching risk that justifies a separate supervisor node. Cheaper and simpler when the graph's invariants are not load-bearing.