state-management
STATE.md reading, writing, and field-level updates. Provides cross-session state persistence via .planning/STATE.md with structured fields for current task, completed phases, blockers, decisions, and quick tasks.
Install / Use
npx skills add a5c-ai/babysitter --skill state-managementInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
AutomationSupported Platforms
Tags
Our assessment of state-management
state-management scores 92/100 on our quality scale, 877th of 2,790 Automation skills we index (top 32%).
Its SKILL.md is 6.9 KB long, well organised into 25 sections with 8 code examples: a thorough specification that gives an agent plenty to work with.
With 1,809 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so state-management is actively maintained.
- Our last check on 2026-10-27 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-09-30. Automated pattern scan on 2026-09-30. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
state-management compared with similar skills
All 4 of these similar skills score higher than state-management; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| state-management (this skill)by a5c-ai | 92 | 1.8k | 2mo ago | SKILL.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 81.9k | today | CLAUDE.md |
| Claude-Code-Game-Studiosby Donchitos | 100 | 39.7k | 7d ago | CLAUDE.md |
| Scraplingby D4Vinci | 100 | 103.6k | 2d ago | MCP Server |
Frequently asked questions
- How do I install state-management?
- Run
npx skills add a5c-ai/babysitter --skill state-management. The install tabs above show the steps for each supported agent. - Which AI agents does state-management work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is state-management safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is state-management still maintained?
- The repository was last updated about 2 months ago, so state-management is actively maintained.
Skill content
View source on GitHubname: state-management description: STATE.md reading, writing, and field-level updates. Provides cross-session state persistence via .planning/STATE.md with structured fields for current task, completed phases, blockers, decisions, and quick tasks. allowed-tools: Read Write Edit Glob metadata: author: babysitter-sdk version: "1.0.0" category: gsd-core backlog-id: SK-GSD-002 graph: domains: [domain:software-engineering] skillAreas: [skill-area:agentic-loops, skill-area:orchestration-loop] workflows: [workflow:feature-development] topics: [topic:developer-experience] roles: [role:tech-lead, role:backend-engineer]
- What is currently being worked on (
current_task,current_phase) - What has been completed (
completed_phases) - What is blocking progress (
blockers) - What decisions have been made (
decisions) - Quick task status (
quick_taskstable) - Session metadata (
last_updated,session_count)
This skill corresponds to the original lib/state.cjs module in the GSD system. Every GSD process reads STATE.md at startup and writes updates at completion.
Capabilities
1. Read Full State
Parse STATE.md into structured fields:
---
last_updated: 2026-03-02T14:30:00Z
session_count: 12
current_milestone: v1.0
---
# Project State
## Current Work
- **Phase**: 72
- **Task**: Implement OAuth2 login flow
- **Status**: executing
- **Plan**: PLAN-1.md (task 3 of 5)
## Completed Phases
- [x] Phase 70: Project setup and scaffolding
- [x] Phase 71: Database schema and migrations
## Blockers
- [ ] [HIGH] API key for OAuth provider not configured (@user, 2026-03-01)
## Decisions
| Date | Decision | Rationale |
|------|----------|-----------|
| 2026-02-28 | Use PostgreSQL over SQLite | Need concurrent writes for API |
| 2026-03-01 | Skip Phase 71.1 (Redis cache) | Not needed for v1.0 |
## Quick Tasks
| # | Task | Status | Date |
|---|------|--------|------|
| 001 | Fix login redirect | done | 2026-02-28 |
| 002 | Add rate limiting | in-progress | 2026-03-02 |
2. Update Individual Fields
Update a single field without affecting the rest of the document:
update current_phase -> 73
update current_task -> "Build API endpoints for user management"
update status -> "planning"
Use Edit tool to perform surgical updates on specific lines.
3. Append to List Fields
Add items to list-type fields:
append completed_phases -> "Phase 72: OAuth2 authentication"
append decisions -> { date: "2026-03-02", decision: "Use JWT tokens", rationale: "Stateless auth for API" }
append blockers -> { severity: "MEDIUM", description: "Need design mockups", owner: "@designer" }
4. Remove from List Fields
Remove items when resolved:
remove blocker -> "API key for OAuth provider not configured"
Mark blockers as resolved rather than deleting (change [ ] to [x]).
5. Quick Tasks Table Management
Add, update, and query quick tasks:
add_quick_task -> { number: 3, task: "Update README", status: "pending" }
update_quick_task -> { number: 2, status: "done" }
query_quick_tasks -> { status: "in-progress" }
6. Cross-Session Memory
STATE.md persists across context resets. On session start:
- Read STATE.md to restore project context
- Increment
session_countin frontmatter - Update
last_updatedtimestamp - Report state summary to orchestrator
7. Decision Log
Structured decision tracking with timestamps and rationale:
| Date | Decision | Rationale |
|------|----------|-----------|
| 2026-03-02 | Use JWT tokens | Stateless auth for API |
8. Blocker Tracking
Track blockers with severity and ownership:
- [ ] [HIGH] API key not configured (@user, 2026-03-01)
- [x] [MEDIUM] Design mockups needed (@designer, 2026-02-28) - resolved 2026-03-01
Severity levels: HIGH (blocks current work), MEDIUM (blocks future work), LOW (inconvenience).
Tool Use Instructions
Reading State
- Use
Readto load.planning/STATE.md - Parse frontmatter for metadata (last_updated, session_count, current_milestone)
- Parse markdown sections into structured fields
- Return parsed state object
Updating a Field
- Use
Readto load current STATE.md - Locate the target field/section
- Use
Editwith precise old_string/new_string to update only the target - Verify edit succeeded by reading the section back
Appending to Lists
- Use
Readto find the end of the target list section - Use
Editto insert new item at the correct position - For tables, append new row before the section break
Resolving Blockers
- Use
Readto find the blocker text - Use
Editto change- [ ]to- [x]and append resolution date
Process Integration
This skill is used by most GSD processes:
execute-phase.js- Update current_task as each task completes, track positionverify-work.js- Add/resolve blockers based on verification resultsaudit-milestone.js- Read completed_phases for coverage analysisprogress.js- Read full state for progress display and routingquick.js- Add/update quick tasks tabledebug.js- Track debug sessions, add blockers for unresolved issuescomplete-milestone.js- Clear completed_phases, reset current_taskadd-tests.js- Update state with test coverage info
Output Format
{
"operation": "read|update|append|remove",
"field": "current_phase|completed_phases|blockers|decisions|quick_tasks",
"status": "success|error",
"previousValue": "...",
"newValue": "...",
"stateSnapshot": {
"currentPhase": 72,
"currentTask": "Implement OAuth2",
"completedPhases": [70, 71],
"activeBlockers": 1,
"quickTasksTotal": 3,
"quickTasksPending": 1
}
}
Configuration
| Setting | Default | Description |
|---------|---------|-------------|
| stateFile | .planning/STATE.md | Path to STATE.md |
| autoTimestamp | true | Auto-update last_updated on write |
| autoSessionCount | true | Auto-increment session_count on read |
| blockerSeverityLevels | HIGH,MEDIUM,LOW | Valid blocker severities |
Error Handling
| Error | Cause | Resolution |
|-------|-------|------------|
| STATE.md not found | Planning directory not initialized | Run gsd-tools init first |
| Section not found | Unexpected STATE.md format | Rebuild STATE.md from template |
| Edit collision | Non-unique text match for edit | Provide more context in old_string |
| Frontmatter parse error | Malformed YAML frontmatter | Fix YAML syntax or regenerate |
| Concurrent modification | Multiple processes editing state | STATE.md is not lock-protected; serialize access |
Constraints
- STATE.md must remain human-readable markdown at all times
- Never delete historical entries (blockers, decisions); mark as resolved instead
- Frontmatter must be valid YAML
- Quick task numbers must be sequential
- All timestamps must be ISO 8601 format
- Decision log must be append-only (no editing past decisions)
- Blocker resolution must preserve the original blocker text
Related Skills
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
ruflo
81.9k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
Claude-Code-Game-Studios
39.7kTurn Claude Code into a full game dev studio — 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.
Scrapling
103.6k🕷️ The BEST Web Scraping framework that handles everything from a single request to a full-scale crawl! Don't be shy, join here: https://discord.gg/EMgGbDceNQ and follow here for daily tips and tricks: https://x.com/Scrapling_dev
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
