Superself
Unverified●30/40Claude Code◐PartialHas SKILL.md but declares no allowed-tools — Claude Code will ask for permission each time
Cursor◐PartialPlain prose you can paste in — but no Cursor rules file
Codex◐PartialPlain prose you can paste in — but no AGENTS.md
Gemini CLI◐PartialPlain prose you can paste in
Copilot◐PartialPlain prose you can paste in — but no Copilot instructions file
npx agentalley add superselfWho is stuck, and on what
Use when a project keeps its state in Superself (a `<!-- superself:begin` block in AGENTS.md or CLAUDE.md, or `self setup` resolves the directory to a registered project): read `self context` at session start, attach work to a work unit, report with evidence, and record confirmed decisions so the next session picks up where this one left off.
The whole source
Frontmatter — 2 properties
| name | superself |
|---|---|
| description | Use when a project keeps its state in Superself (a `<!-- superself:begin` block in AGENTS.md or CLAUDE.md, or `self setup` resolves the directory to a registered project): read `self context` at session start, attach work to a work unit, report with evidence, and record confirmed decisions so the next session picks up where this one left off. |
| 1 | --- |
| 2 | name: superself |
| 3 | description: 'Use when a project keeps its state in Superself (a `<!-- superself:begin` block in AGENTS.md or CLAUDE.md, or `self setup` resolves the directory to a registered project): read `self context` at session start, attach work to a work unit, report with evidence, and record confirmed decisions so the next session picks up where this one left off.' |
| 4 | ---A5 — No allowed-tools declared — no way to tell what this skill may touch |
| 5 | |
| 6 | # Superself |
| 7 | |
| 8 | Superself is an Apache-2.0 CLI (`npm install -g [email protected]`, Node 22.12+) that |
| 9 | version-controls a project's state — goals, decisions, work units, reports — |
| 10 | as an append-only event log in a git repository separate from the code. The |
| 11 | state is derived on demand, so nothing in it is hand-maintained. This skill |
| 12 | tells an agent how to read and write that state through the `self` CLI. It is |
| 13 | maintained by the Superself authors: https://github.com/fxylabs/superself |
| 14 | |
| 15 | ## When this skill applies |
| 16 | |
| 17 | - The project's `AGENTS.md` or `CLAUDE.md` contains a block between |
| 18 | `<!-- superself:begin` and `<!-- superself:end -->`, or `self setup` prints |
| 19 | the workspace, project, and store this directory resolves to. |
| 20 | - Skip the skill when `self --version` fails: the project does not use |
| 21 | Superself, and nothing below should be invented by hand. This skill is |
| 22 | written against `[email protected]`; a different major or minor version may |
| 23 | have moved a verb or flag, so check `self <command> --help` before relying |
| 24 | on one. |
| 25 | |
| 26 | ## Session start |
| 27 | |
| 28 | 1. Run `self context` and treat its output as current truth: the goal, active |
| 29 | decisions and conventions, open work, recent reports. It is folded from the |
| 30 | log, never written by hand. |
| 31 | 2. Something missing from context was placed out of the rendered set on |
| 32 | purpose; `self search <query>` finds live records context left out, and |
| 33 | `self work show <id>` prints one unit's full brief and report history. |
| 34 | |
| 35 | ## While working |
| 36 | |
| 37 | - Substantive work attaches to a work unit. Create one with |
| 38 | `self work add "<required outcome>"` — the outcome is what must become true, |
| 39 | not the task — then `self work start <id>`. `start` reads the brief and |
| 40 | records that this session picked the unit up; if another session holds it, |
| 41 | the CLI says who and since when and does not refuse. Judge and proceed. |
| 42 | - After committing, report progress: `self report <id> "<what happened>"`. The |
| 43 | current HEAD commit is attached as evidence automatically; `--evidence |
| 44 | <commit|note>` attaches something else, `--file <path>` attaches a longer |
| 45 | brief. |
| 46 | - Record a decision the user confirmed: `self decide "<text>" --why "<reason>"`. |
| 47 | Use `--proposed` when the user has not confirmed it. One decision per event. |
| 48 | - Blocked? `self work block <id> --on decision|dependency|external --why "..."`. |
| 49 | Superseded or moved? `self work retire <id> --why "..." [--successor <id>]`. |
| 50 | Never mark such a unit done, and never leave it falsely blocked. |
| 51 | - Found a gap between an objective and the current state? Propose the work with |
| 52 | `self work propose` and its brief; the user accepts or declines it. |
| 53 | - The user approved a next step or a continuation? Register it at once with |
| 54 | `self work add` and the context behind it. A plan that lives only in the |
| 55 | conversation is lost when the conversation ends. |
| 56 | |
| 57 | ## Closing |
| 58 | |
| 59 | - `self work done <id>` closes a unit only when a report carries a commit or an |
| 60 | artifact, or the done itself states what verifiably happened: |
| 61 | `self work done <id> --report "<what verifiably happened>"`. A bare claim is |
| 62 | refused, and declared criteria gate it until each is covered. |
| 63 | - A record's text is immutable once confirmed. Correct it by restating: |
| 64 | `--supersedes <id>` on any add verb records the new wording and keeps the |
| 65 | lineage. `retract` withdraws a record with nothing replacing it. |
| 66 | |
| 67 | ## Rules that keep the state trustworthy |
| 68 | |
| 69 | - Records — events, decisions, reports, conventions — are written in English |
| 70 | so whoever opens them next can read them; answer the person in their own |
| 71 | language. |
| 72 | - A branch reaches main through a pull request: PR review and CI own merge |
| 73 | control. Superself owns context and the work graph, not the merge gate. |
| 74 | - Never hand-edit generated state files or anything under `.superself/`. |
| 75 | - In a project without a superself block, run `self setup` first. If it |
| 76 | resolves the directory to a registered project, ask the user once whether |
| 77 | to run `self connect`, which writes the managed block into `AGENTS.md` or |
| 78 | `CLAUDE.md`. If it resolves no project, ask once whether to register it with |
| 79 | `self project init`. Never register or connect a project on your own. |
| 80 | |
| 81 | ## Going deeper |
| 82 | |
| 83 | `self --help` lists every verb; `self <command> --help` prints one command's |
| 84 | flags without touching state. Topic guides ship with the CLI: |
| 85 | |
| 86 | - `self help agents` — how a session drives this CLI, start to finish |
| 87 | - `self help context` — what `self context` renders, and why something is missing from it |
| 88 | - `self help records` — one entity behind every record kind, and how a record is corrected |
| 89 | - `self help placement` — scope, priority and exposure — how a record earns its place in context |
| 90 | - `self help work` — the work graph: outcomes, evidence, criteria, and proposals |
| 91 | - `self help goals` — long-term goals, objectives, milestones, and what reaching one takes |
| 92 | - `self help workspace` — the store, the projects in it, and moving it between machines |
| 93 |
Reviews
Installed this one?Write the first review and take the Trailblazer badge.
Alternatives
Structure Your Invention For A Patent FilingDescribe your invention in plain words and get back a formal write-up that lays out the problem it solves, how it works, and which parts are worth protecting.●····●37/40Claims Drafting: The Core Patent SkillDescribe your invention in plain words and get back a numbered set of formal patent claims — the legal wording that defines exactly what you own.●····●36/40Patent Novelty and Non-Obviousness CheckDescribe your invention in everyday words and get back a clear read on whether it's new and original enough to patent, plus where it might hit trouble.●····●35/40Patent Pipeline: From Invention to FilingDescribe your invention in plain words and get back a complete first-draft patent application — claims, full description, and abstract — ready to hand to a patent attorney.●····●35/40