New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Superself

by wshobson in wshobson/agents

A skill your agent uses 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…

MITAuto-check passedAgent Workflows

Install Superself

skills CLI
$ npx skills add wshobson/agents --skill superself -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install wshobson/agents superself --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/wshobson/agents.git skills-src && mkdir -p .claude/skills && cp -r skills-src/plugins/superself/skills/superself .claude/skills/superself && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
superself
GitHub stars
40k
Token cost
~1.3k tokens
SKILL.md length
748 words
Files
1
Skills in repo
142
Repo updated
First seen
Licence
MIT

At a glance

A skill your agent uses 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…

  • Works in 2 steps: Run self context and treat its output as… → Something missing from context was…
  • A project keeps its state in Superself (a <!-- superself:begin block in AGENTS.md
  • SKILL.md covers When this skill applies, Session start, While working and Closing, plus 2 more sections
  • Calls npm

What it does

Superself is an agent skill from wshobson/agents. 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.

Its SKILL.md is about 1.3k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Agent Workflows, covering Agent instruction files. The repository describes itself as: Multi-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, Google Antigravity, and Pi. The licence is MIT.

When your agent uses it

  • A project keeps its state in Superself (a <!-- superself:begin block in AGENTS.md
  • Self setup resolves the directory to a registered project): read self context at session start
  • Attach work to a work unit
  • Report with evidence

Example prompts

  • “/superself”

Requirements

  • Node.js

Workflow steps

2 steps, taken from the first numbered list in SKILL.md.

  1. Run self context and treat its output as current truth: the goal, active
  2. Something missing from context was placed out of the rendered set on

What it can do on your machine

Read from SKILL.md and the folder at commit 46891e7. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • npm

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Links to these hosts (documentation or services it may open):

    • github.com

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Superself loads about 1.3k tokens when it runs. Until then it costs about 89 tokens; SKILL.md has 748 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~89
When it runs · the whole SKILL.md, loaded when a task matches
~1.3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from wshobson/agents at commit 46891e7, republished under its MIT licence (© wshobson). 748 words, ~1,321 tokens.

Download SKILL.mdSave it as .claude/skills/superself/SKILL.md (or your agent's skills folder).
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.

Superself

Superself is an Apache-2.0 CLI (npm install -g superself@0.6.1, Node 22.12+) that version-controls a project's state — goals, decisions, work units, reports — as an append-only event log in a git repository separate from the code. The state is derived on demand, so nothing in it is hand-maintained. This skill tells an agent how to read and write that state through the self CLI. It is maintained by the Superself authors: https://github.com/fxylabs/superself

When this skill applies

  • The project's AGENTS.md or CLAUDE.md contains a block between <!-- superself:begin and <!-- superself:end -->, or self setup prints the workspace, project, and store this directory resolves to.
  • Skip the skill when self --version fails: the project does not use Superself, and nothing below should be invented by hand. This skill is written against superself@0.6.1; a different major or minor version may have moved a verb or flag, so check self <command> --help before relying on one.

Session start

  1. Run self context and treat its output as current truth: the goal, active decisions and conventions, open work, recent reports. It is folded from the log, never written by hand.
  2. Something missing from context was placed out of the rendered set on purpose; self search <query> finds live records context left out, and self work show <id> prints one unit's full brief and report history.

While working

  • Substantive work attaches to a work unit. Create one with self work add "<required outcome>" — the outcome is what must become true, not the task — then self work start <id>. start reads the brief and records that this session picked the unit up; if another session holds it, the CLI says who and since when and does not refuse. Judge and proceed.
  • After committing, report progress: self report <id> "<what happened>". The current HEAD commit is attached as evidence automatically; --evidence <commit|note> attaches something else, --file <path> attaches a longer brief.
  • Record a decision the user confirmed: self decide "<text>" --why "<reason>". Use --proposed when the user has not confirmed it. One decision per event.
  • Blocked? self work block <id> --on decision|dependency|external --why "...". Superseded or moved? self work retire <id> --why "..." [--successor <id>]. Never mark such a unit done, and never leave it falsely blocked.
  • Found a gap between an objective and the current state? Propose the work with self work propose and its brief; the user accepts or declines it.
  • The user approved a next step or a continuation? Register it at once with self work add and the context behind it. A plan that lives only in the conversation is lost when the conversation ends.
Show full SKILL.md (324 more words)Show less

Closing

  • self work done <id> closes a unit only when a report carries a commit or an artifact, or the done itself states what verifiably happened: self work done <id> --report "<what verifiably happened>". A bare claim is refused, and declared criteria gate it until each is covered.
  • A record's text is immutable once confirmed. Correct it by restating: --supersedes <id> on any add verb records the new wording and keeps the lineage. retract withdraws a record with nothing replacing it.

Rules that keep the state trustworthy

  • Records — events, decisions, reports, conventions — are written in English so whoever opens them next can read them; answer the person in their own language.
  • A branch reaches main through a pull request: PR review and CI own merge control. Superself owns context and the work graph, not the merge gate.
  • Never hand-edit generated state files or anything under .superself/.
  • In a project without a superself block, run self setup first. If it resolves the directory to a registered project, ask the user once whether to run self connect, which writes the managed block into AGENTS.md or CLAUDE.md. If it resolves no project, ask once whether to register it with self project init. Never register or connect a project on your own.

Going deeper

self --help lists every verb; self <command> --help prints one command's flags without touching state. Topic guides ship with the CLI:

  • self help agents — how a session drives this CLI, start to finish
  • self help context — what self context renders, and why something is missing from it
  • self help records — one entity behind every record kind, and how a record is corrected
  • self help placement — scope, priority and exposure — how a record earns its place in context
  • self help work — the work graph: outcomes, evidence, criteria, and proposals
  • self help goals — long-term goals, objectives, milestones, and what reaching one takes
  • self help workspace — the store, the projects in it, and moving it between machines

© wshobson, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in plugins/superself/skills/superself of wshobson/agents.

Open the folder on GitHubat commit 46891e7

Compare with similar skills

Superself next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Superself compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Superself this skillwshobson/agents40k—~1.3kAutomated safety check: PassMIT
Using Agent Skillsaddyosmani/agent-skills103k4 repos~2.4kAutomated safety check: PassMIT
Claude ReflectBayramAnnakov/claude-reflect1.7k2 repos~627Automated safety check: PassMIT
Writing For Agentsbestofjs/bestofjs3.1k19 repos~2.7kAutomated safety check: PassMIT
Neat-Freak Knowledge CloseoutKKKKhazix/khazix-skills21k—~1.9kAutomated safety check: PassMIT
Task Observerrebelytics/one-skill-to-rule-them-all3.2k1 repos~12kAutomated safety check: PassCC-BY-4.0

Similar skills

  • Using Agent Skills

    addyosmani/agent-skills

    Meta-skill for choosing which workflow skill fits the task at hand, plus always-on habits: surface assumptions, stop on confusion, push back, keep it simple and stay in scope.

    103k GitHub starsUsed in 4 repos~2.4k tokens
    Agent WorkflowsAuto-check passed

  • Claude Reflect

    BayramAnnakov/claude-reflect

    Self-learning system that captures corrections during sessions and reminds users to run /reflect to update CLAUDE.md.

    1.7k GitHub starsUsed in 2 repos~627 tokens
    Agent WorkflowsAuto-check passed

  • Writing For Agents

    bestofjs/bestofjs

    Writing documents for agents. An agent skill from bestofjs/bestofjs.

    3.1k GitHub starsUsed in 19 repos~2.7k tokens
    Agent WorkflowsAuto-check passed

  • Neat-Freak Knowledge Closeout

    KKKKhazix/khazix-skills

    Brings project docs, agent rule files, authorized memory and leftover workspace files back in line with what the code and runtime actually do at the end of a work session.

    21k GitHub stars~1.9k tokensUpdated 7 days ago
    Agent WorkflowsAuto-check passed

  • Task Observer

    rebelytics/one-skill-to-rule-them-all

    Monitors task execution for skill improvement opportunities.

    3.2k GitHub starsUsed in 1 repo~12k tokens
    Agent WorkflowsAuto-check passed

  • SkillOpt Sleep Cycle

    microsoft/SkillOpt

    Official

    Runs an on-demand or nightly sleep cycle that reviews past Claude Code sessions and proposes validated updates to CLAUDE.md and skills.

    18k GitHub stars~2.3k tokensUpdated 2 days ago
    Agent WorkflowsAuto-check passed

More from wshobson/agents

All 142 skills in this repo

  • Billing Automation

    wshobson/agents

    Covers building subscription billing: billing cycles, subscription states, invoice generation, proration, tax handling and dunning for failed payments.

    40k GitHub starsUsed in 14 repos~473 tokens
    Auto-check passed

  • Cloud Cost Optimization

    wshobson/agents

    Cuts cloud spend across AWS, Azure, GCP and OCI with cost tagging, rightsizing, commitment and spot pricing models, and architecture changes.

    40k GitHub starsUsed in 14 repos~1.7k tokens
    Auto-check passed

  • Python Performance Optimization

    wshobson/agents

    Profiles slow Python code with cProfile and memory profilers, then applies targeted fixes for CPU, memory, I/O and query bottlenecks.

    40k GitHub starsUsed in 13 repos~814 tokens
    Auto-check passed

  • Portfolio Risk Metrics

    wshobson/agents

    Covers portfolio risk measurement with VaR, CVaR, Sharpe, Sortino and drawdown, plus guidance on limits, stress tests and tail risk.

    40k GitHub starsUsed in 13 repos~502 tokens
    Auto-check passed

  • Bats Shell Testing Patterns

    wshobson/agents

    Writes unit tests for shell scripts with Bats: error-condition tests, fixtures and mocks, cross-shell checks, parallel runs, helper files and CI integration.

    40k GitHub starsUsed in 12 repos~1.3k tokens
    Auto-check passed

  • DGX Spark Memory and Thermal Ops

    wshobson/agents

    Plans memory headroom, works through out-of-memory failures and watches temperature and power during long ML training jobs on NVIDIA DGX Spark.

    40k GitHub starsUsed in 1 repo~2k tokens
    Auto-check passed

Categories

Questions about Superself

What does Superself do?

A skill your agent uses 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…. Superself is an agent skill from wshobson/agents.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.

When should I use Superself?

Superself fits situations like: A project keeps its state in Superself (a <!-- superself:begin block in AGENTS.md; self setup resolves the directory to a registered project): read self context at session start; attach work to a work unit; report with evidence.

How do I install Superself in Claude Code?

Run `npx skills add wshobson/agents --skill superself -a claude-code`. Or copy the skill folder (plugins/superself/skills/superself in wshobson/agents) into .claude/skills/superself in your project. Claude Code loads it when a task matches its description.

How do I install Superself in Codex?

Run `npx skills add wshobson/agents --skill superself -a codex`. Or copy the skill folder (plugins/superself/skills/superself in wshobson/agents) into .agents/skills/superself in your project. Codex loads it when a task matches its description.

Can I use Superself in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add wshobson/agents --skill superself -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/superself, .gemini/skills/superself, .github/skills/superself and .opencode/skills/superself in your project.

What does Superself need to run?

Going by SKILL.md and its folder, Superself needs the command-line tools its instructions call (npm). Our summary lists: Node.js.

Does Superself access the network?

SKILL.md names 1 domain. As links in the text: github.com. This is read from the text; nothing was executed.

Is Superself safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Superself use?

Superself is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Superself use?

About 1.3k tokens (SKILL.md is roughly 5.3k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Superself?

Skills that share tags, products or a category with Superself: Using Agent Skills (addyosmani/agent-skills, 103k stars), Claude Reflect (BayramAnnakov/claude-reflect, 1.7k stars), Writing For Agents (bestofjs/bestofjs, 3.1k stars) and Neat-Freak Knowledge Closeout (KKKKhazix/khazix-skills, 21k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Superself?

wshobson (a GitHub user) maintains it in wshobson/agents, which has 40,287 GitHub stars. The repository holds 142 skills in this directory. The repository was last updated on October 5, 2026.

Source: wshobson/agents on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.