Agent skill

Statem

by henryqin1997 in henryqin1997/statem

A skill your agent uses when a long coding or research task should be managed with statem state-machine runbooks, including creating specs, starting or resuming runs, checking current state…

Apache-2.0Auto-check passedDevOps & Cloud

Install Statem

skills CLI

$ npx skills add henryqin1997/statem --skill statem -a claude-code

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

GitHub CLI

$ gh skill install henryqin1997/statem statem --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/henryqin1997/statem.git skills-src && mkdir -p .claude/skills && cp -r skills-src/plugins/statem/skills/statem .claude/skills/statem && 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/

Paste into Claude Code

Install the "statem" agent skill from https://github.com/henryqin1997/statem/tree/main/plugins/statem/skills/statem into .claude/skills/statem/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "statem", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

$skill-installer

$skill-installer install https://github.com/henryqin1997/statem/tree/main/plugins/statem/skills/statem

Type this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.

skills CLI

$ npx skills add henryqin1997/statem --skill statem -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install henryqin1997/statem statem --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/henryqin1997/statem.git skills-src && mkdir -p .agents/skills && cp -r skills-src/plugins/statem/skills/statem .agents/skills/statem && rm -rf skills-src

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "statem" agent skill from https://github.com/henryqin1997/statem/tree/main/plugins/statem/skills/statem into .agents/skills/statem/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "statem", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add henryqin1997/statem --skill statem -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install henryqin1997/statem statem --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/henryqin1997/statem.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/plugins/statem/skills/statem .cursor/skills/statem && rm -rf skills-src

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "statem" agent skill from https://github.com/henryqin1997/statem/tree/main/plugins/statem/skills/statem into .cursor/skills/statem/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "statem", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

gemini skills install

$ gemini skills install https://github.com/henryqin1997/statem.git --path plugins/statem/skills/statem

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add henryqin1997/statem --skill statem -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install henryqin1997/statem statem --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/henryqin1997/statem.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/plugins/statem/skills/statem .gemini/skills/statem && rm -rf skills-src

Use ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "statem" agent skill from https://github.com/henryqin1997/statem/tree/main/plugins/statem/skills/statem into .gemini/skills/statem/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "statem", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install henryqin1997/statem statem

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add henryqin1997/statem --skill statem -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

$ git clone --depth 1 https://github.com/henryqin1997/statem.git skills-src && mkdir -p .github/skills && cp -r skills-src/plugins/statem/skills/statem .github/skills/statem && rm -rf skills-src

Use ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "statem" agent skill from https://github.com/henryqin1997/statem/tree/main/plugins/statem/skills/statem into .github/skills/statem/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "statem", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add henryqin1997/statem --skill statem -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install henryqin1997/statem statem --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/henryqin1997/statem.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/plugins/statem/skills/statem .opencode/skills/statem && rm -rf skills-src

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "statem" agent skill from https://github.com/henryqin1997/statem/tree/main/plugins/statem/skills/statem into .opencode/skills/statem/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "statem", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: statem
GitHub stars: 1.3k
Token cost: ~1.2k tokens
SKILL.md length: 617 words
Files: 1
Skills in repo: 2
Repo updated: Sep 2, 2026
First seen: Oct 7, 2026
Licence: Apache-2.0

At a glance

A skill your agent uses when a long coding or research task should be managed with statem state-machine runbooks, including creating specs, starting or resuming runs, checking current state…

Works in 7 steps: Find or create a statem spec such as… → Validate it: python3 -m statem validate… → Start or resume a run: python3 -m statem… → …
Research task should be managed with statem state-machine runbooks
SKILL.md covers Workflow, Context Clear, Loop Compaction and Auto Loop Hook, plus 1 more section
Calls python3

What it does

Statem is an agent skill from henryqin1997/statem. Use when a long coding or research task should be managed with statem state-machine runbooks, including creating specs, starting or resuming runs, checking current state, transitioning with goto, saving progress, and reading history.

Its SKILL.md is about 1.2k 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 DevOps & Cloud, covering Runbooks and postmortems. It works with Python. The repository describes itself as: CLI runbook for agent long run. The licence is Apache-2.0.

When your agent uses it

Research task should be managed with statem state-machine runbooks
Including creating specs
Checking current state
Transitioning with goto

Example prompts

“/statem”

Requirements

Python 3

Workflow steps

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

Find or create a statem spec such as statem.yaml.
Validate it: python3 -m statem validate statem.yaml --json.
Start or resume a run: python3 -m statem start statem.yaml --run-id --json.
Check state before acting: python3 -m statem cur --run-id --json.
Move only through allowed edges: python3 -m statem goto --run-id --json.
Save progress before pausing: python3 -m statem save --run-id --json.
For handoff context, read recent history: python3 -m statem history --run-id --tail 10 --json.

What it can do on your machine

Read from SKILL.md and the folder at commit 8c3309a. 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:
- python3
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md.
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

Statem loads about 1.2k tokens when it runs. Until then it costs about 60 tokens; SKILL.md has 617 words of instructions outside code blocks.

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

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 henryqin1997/statem at commit 8c3309a, republished under its Apache-2.0 licence (© henryqin1997). 617 words, ~1,151 tokens.

Download SKILL.mdSave it as .claude/skills/statem/SKILL.md (or your agent's skills folder).

name: statem
description: Use when a long coding or research task should be managed with statem state-machine runbooks, including creating specs, starting or resuming runs, checking current state, transitioning with goto, saving progress, and reading history.

Statem

Use statem when the task is long-running, iterative, easy to lose track of, or benefits from explicit agent state. Prefer it as a runbook, not as a rigid harness.

Workflow

Find or create a statem spec such as statem.yaml.
Validate it: python3 -m statem validate statem.yaml --json.
Start or resume a run: python3 -m statem start statem.yaml --run-id <id> --json.
Check state before acting: python3 -m statem cur --run-id <id> --json.
Move only through allowed edges: python3 -m statem goto <node> --run-id <id> --json.
Save progress before pausing: python3 -m statem save --run-id <id> --json.
For handoff context, read recent history: python3 -m statem history --run-id <id> --tail 10 --json.

Use statem instead of python3 -m statem if the CLI is installed on PATH.

For dynamic servers, company machines, or disposable git checkouts, prefer a machine-local state directory. Set STATEM_STATE_DIR once, for example $HOME/.local/state/statem/<project>, so runtime state survives checkout replacement. After moving to a new checkout, run statem start <spec> --run-id <id> once to rebind the run to the current spec path.

Commit YAML runbooks with the repo. Do not commit runtime state; treat .statem/ or STATEM_STATE_DIR as local, copy-on-use execution data.

Context Clear

Avoid /clear in normal loops. It flushes the conversation, including any instructions that were supposed to run after it, and can lose useful intent that was not written to durable files. Prefer explicit transitions plus safe compaction.

Before a hard clear, generate a durable resume prompt:

bash

python3 -m statem prompt --run-id <id>

Paste the generated prompt immediately after /clear. The agent must recover from .statem with start, cur, and history; it should not rely on any pre-clear conversation.

Loop Compaction

For cyclic runbooks, prefer an explicit session hygiene node after a full loop. When continuing another cycle and context is noisy, generate a safe compaction instruction:

bash

python3 -m statem compact-prompt --run-id <id>

Run the generated /compact instruction through the host UI, then recover with statem cur and statem history --tail 10. Do not use hidden self-messaging to trigger compaction.

Agents may inspect the full graph with statem state; cur, next, and goto are for disciplined execution and attention anchoring, not for hiding the runbook.

Show full SKILL.md (263 more words)Show less

Auto Loop Hook

When the host supports a Stop hook, users may opt into auto-loop behavior with integrations/hooks/statem_stop_hook.py. The hook runs when the agent is about to hand control back to the user. If a statem run is active, the current node is not a terminal/handoff node, and there are outgoing transitions, it returns a continuation prompt that tells the agent to inspect statem cur and keep working from the current node.

Registration examples live in:

examples/hooks/README.md
examples/hooks/codex-stop-autoloop.hooks.json
examples/hooks/claude-stop-autoloop.settings.json

Merge the matching snippet into the host hook configuration and use an absolute script path if the hook is registered outside the statem repository.

Treat this as host-level glue. It must not advance state, run /clear, or hide the graph. The agent should still transition only with statem goto.

Authoring Specs

Keep the static spec separate from .statem/ runtime state.
Use natural-language checks for low-friction runbooks.
Use in_hook for setup after entering a node.
Use before_transfer for redo/check loops while still in the current node. It is a spec field, not a CLI command; statem goto runs it automatically.
Use out_hook to persist current-node progress before leaving.
Use edge hook as prepare-transfer work after out_hook and before entering the target. If a blocking edge hook fails, the pointer stays at the source so the agent can retry.
Use type: command for deterministic shell checks.
Use type: predicate for file existence, non-empty files, text matches, and JSON-path checks.
Use type: llm_review when another model, agent, or script should review before a transition.

Do not manually edit .statem/runs/<run-id>/state.json unless the user explicitly asks for runtime surgery.

Files

Just SKILL.md in plugins/statem/skills/statem of henryqin1997/statem.

Open the folder on GitHubat commit 8c3309a

Compare with similar skills

Statem 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.

Statem compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Statem this skillhenryqin1997/statem	1.3k	—	~1.2k	Automated safety check: Pass	Apache-2.0	1 mo ago
Knowledge Opsalirezarezvani/claude-skills	28k	—	~4.1k	Automated safety check: Pass	MIT	1 mo ago
Flowfile Node DevelopmentEdwardvaneechoud/Flowfile	373	—	~9.3k	Automated safety check: Pass	MIT	today
Halo Ticket Contextautomateyournetwork/netclaw	675	—	~1.8k	Automated safety check: Pass	Apache-2.0	3 days ago
Python Debugpyopenclaw/openclaw	392k	1 repos	~633	Automated safety check: Pass	MIT	today
Night Market Operationsathola/claude-night-market	342	—	~3.6k	Automated safety check: Pass	MIT	2 days ago

Similar skills

Knowledge Ops
alirezarezvani/claude-skills
A skill your agent uses when a Head of Ops, Knowledge Manager, or TPM-Internal needs to author, validate, or clean up company SOPs and internal runbooks (procurement intake, vendor offboarding…
28k GitHub stars~4.1k tokensUpdated 1 mo ago
DevOps & CloudAuto-check passed
Flowfile Node Development
Edwardvaneechoud/Flowfile
End-to-end runbook for adding or modifying a Flowfile node type across all four layers (flowfilecore settings/graph/template, flowfilefrontend UI registry, flowfileframe Python API, flowfilewasm…
373 GitHub stars~9.3k tokensUpdated today
DevOps & CloudAuto-check passed
Halo Ticket Context
automateyournetwork/netclaw
Review a HaloPSA / HaloITSM ticket for resolution context — its detail, action/note history, linked assets, and related KB runbooks — read-only.
675 GitHub stars~1.8k tokensUpdated 3 days ago
DevOps & CloudAuto-check passed
Python Debugpy
openclaw/openclaw
Debug Python with pdb, breakpoint(), post-mortem inspection, and debugpy remote attach.
392k GitHub starsUsed in 1 repo~633 tokens
Frontend & DesignAuto-check passed
Night Market Operations
athola/claude-night-market
Run and ship this repo: make targets, artifacts, release runbook.
342 GitHub stars~3.6k tokensUpdated 2 days ago
DevelopmentAuto-check passed
Trader Memory Core
tradermonty/claude-trading-skills
Track investment theses across their lifecycle — from screening idea to closed position with postmortem.
3k GitHub starsUsed in 3 repos~4.3k tokens
DevOps & CloudAuto-check passed

Questions about Statem

What does Statem do?

A skill your agent uses when a long coding or research task should be managed with statem state-machine runbooks, including creating specs, starting or resuming runs, checking current state…. Statem is an agent skill from henryqin1997/statem. Use when a long coding or research task should be managed with statem state-machine runbooks, including creating specs, starting or resuming runs, checking current state, transitioning with goto, saving progress, and reading history.

When should I use Statem?

Statem fits situations like: research task should be managed with statem state-machine runbooks; including creating specs; checking current state; transitioning with goto.

How do I install Statem in Claude Code?

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

How do I install Statem in Codex?

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

Can I use Statem 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 henryqin1997/statem --skill statem -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/statem, .gemini/skills/statem, .github/skills/statem and .opencode/skills/statem in your project.

What does Statem need to run?

Going by SKILL.md and its folder, Statem needs the command-line tools its instructions call (python3). Our summary lists: Python 3.

Does Statem access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Statem 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 Statem use?

Statem is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Statem use?

About 1.2k tokens (SKILL.md is roughly 4.6k 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 Statem?

Skills that share tags, products or a category with Statem: Knowledge Ops (alirezarezvani/claude-skills, 28k stars), Flowfile Node Development (Edwardvaneechoud/Flowfile, 373 stars), Halo Ticket Context (automateyournetwork/netclaw, 675 stars) and Python Debugpy (openclaw/openclaw, 392k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Statem?

henryqin1997 (a GitHub user) maintains it in henryqin1997/statem, which has 1,324 GitHub stars. The repository holds 2 skills in this directory. The repository was last updated on September 2, 2026.

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

Statem

Install Statem

Facts

At a glance

What it does

When your agent uses it

Example prompts

Requirements

Workflow steps

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

Statem

Workflow

Context Clear

Loop Compaction

Auto Loop Hook

Authoring Specs

Files

Compare with similar skills

Similar skills

Knowledge Ops

Flowfile Node Development

Halo Ticket Context

Python Debugpy

Night Market Operations

Trader Memory Core

More from henryqin1997/statem

Use Statem

Questions about Statem

Install Statem

Facts

At a glance

What it does

When your agent uses it

Example prompts

Requirements

Workflow steps

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

Statem

Workflow

Context Clear

Loop Compaction

Auto Loop Hook

Authoring Specs

Files

Compare with similar skills

Similar skills

Knowledge Ops

Flowfile Node Development

Halo Ticket Context

Python Debugpy

Night Market Operations

Trader Memory Core

More from henryqin1997/statem

Use Statem

Related

Questions about Statem