Guide · Agent skill
How to use the Superself Project State agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Superself Project State skill teaches an AI agent to read and write a project's state through the self command-line tool. Superself keeps goals, decisions, work units and progress reports in an append-only log stored in a git repository separate from the code. This guide explains what the skill makes the agent do, how to install it, how to trigger it, and what it needs before you rely on it.
Superself Project Statewshobson/agents · MIT Download the skill Quick start
- 1Install the superself CLI. Install Node.js at the minimum version listed on this page, then run the global npm install for the superself CLI.
- 2Confirm the CLI works. Run self --version. If it fails, the project does not use Superself and the skill will not apply.
- 3Set up the project. Make sure AGENTS.md or CLAUDE.md contains a superself block, or run self setup to see which project the directory resolves to.
- 4Install the skill. Unzip the downloaded skill into ~/.claude/skills/ or the project's .claude/skills/, or upload the ZIP under Settings, Capabilities, Skills.
- 5Start a session. Ask the agent to work on the project. It will run self context first and read the current goal, decisions and open work.
- 6Track and report work. Ask the agent to create and start a work unit, then to report progress with evidence after each commit.
What the Superself Project State skill does
Superself is a CLI that version-controls a project's state: goals, decisions, work units and reports. The state is stored as an append-only event log in a git repository separate from the code, and it is derived on demand rather than hand-maintained.
The skill tells the agent to read that state at the start of a session, attach its work to tracked work units, report progress with evidence such as commit hashes, and record decisions the user has confirmed. The next session can then pick up where this one stopped.
Check the requirements before installing
The skill needs Node.js at the minimum version named in the requirements on this page, and the superself CLI installed globally through npm. It also needs a project that already uses Superself: either an AGENTS.md or CLAUDE.md file containing a superself block, or a registered Superself project.
The Superself CLI is licensed under Apache-2.0. This skill is listed under the MIT licence. The skill runs scripts, and it does not use the network according to this listing.
- Node.js at the minimum version listed on this page
- superself CLI installed globally with npm
- A project with a superself block in AGENTS.md or CLAUDE.md, or a registered Superself project
npm install -g superself@0.6.1Install the skill in Claude
Download the skill ZIP from this page and unzip it. Place the skill folder in ~/.claude/skills/ to make it available across your projects, or in a project's .claude/skills/ folder to limit it to that project.
You can also upload the ZIP in the Claude apps under Settings, then Capabilities, then Skills. The skill's entry file is SKILL.md.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside the project
- Claude apps: Settings, then Capabilities, then Skills, then upload the ZIP
How to trigger the skill with natural requests
The skill applies when the project's AGENTS.md or CLAUDE.md contains a block between the superself begin and end markers, or when self setup reports the workspace, project and store for the directory. You do not need a special command; ask for the work in plain language inside that project.
If self --version fails, the skill tells the agent to stop, because the project does not use Superself.
- Start a session with: check the project state before we begin
- Ask for tracked work: add this as a work unit and start it
- Ask to log a decision: record that we agreed to use SQLite, with the reason
What the agent does during a session
At session start, the agent runs self context and treats the output as current truth. Substantive work is attached to a work unit created with self work add, then started with self work start. After committing, the agent reports progress with self report, and the current HEAD commit is attached as evidence automatically.
Decisions the user has confirmed are recorded with self decide. Proposed decisions use the --proposed flag. Blocked or retired work is marked with self work block or self work retire, and a unit is closed with self work done only when a report carries evidence.
- self context: read the goal, decisions, open work and recent reports at session start
- self work add and self work start: create and pick up a unit of work
- self report: log progress with evidence
- self decide: record a confirmed decision, or use --proposed if unconfirmed
- self work done: close a unit with a commit, an artifact or a verified report
self contextSafety notes and tips
The skill runs scripts and writes records into the Superself store on your behalf, so review what it records. Records are written in English, and a confirmed record's text cannot be edited; a correction is recorded with --supersedes. The skill says never to hand-edit generated state files or anything under .superself/.
Branches reach main through a pull request, and PR review and CI control the merge. The skill does not register or connect a project without asking you first. For more detail, run self help agents or self help work.
- Never hand-edit files under .superself/
- Check that self --version works before you start
- Use self <command> --help to confirm flags on your installed version
- Ask before any project is registered or connected
self help agentsWhat people use it for
- Resuming a multi-session feature where the agent needs the previous decisions and open work at session start
- Logging a decision the team confirmed so a later session does not reopen it
- Tracking blocked work with a reason, such as waiting on an external dependency
- Keeping progress reports tied to commit hashes for review
Frequently asked questions
How do I install the superself agent skill?
Download the skill ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings, then Capabilities, then Skills.
What do I need to run the Superself skill?
You need Node.js at the minimum version listed on this page, the superself CLI installed globally through npm, and a project with a superself block in AGENTS.md or CLAUDE.md or a registered Superself project. The skill runs scripts and does not use the network, according to its listing.
Is the Superself skill free?
The skill is listed under the MIT licence and the Superself CLI is listed under Apache-2.0. Check the licence files in the source before you redistribute either one.
Why does the skill say to stop?
If self --version fails, the project does not use Superself. The skill says to stop in that case, because it adds process overhead with no benefit in a project that does not use the tool.
Can I use this skill as a general task manager?
No. The skill is tied to the self CLI and its own store, and the agent writes records into that store on your behalf. For a general task manager, pick a tool built for that purpose.
How is Superself different from hand-edited notes?
Superself keeps state in an append-only event log in a separate git repository, and the state is derived from that log. Confirmed records cannot be edited; corrections are recorded as new entries that supersede the old ones.
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 this skill if you already run the Superself CLI and want AI agents to read and write project state across sessions in a git-backed log. Skip it if your project does not use Superself, or if you only need a general task list, since the agent will write records into the Superself store.
Download the skill