agentsop-session-state-hygiene
Decision protocol for managing the context/session state of an AI coding tool: when to /clear, when to keep context, and how to detect "context bleed" — the failure mode where stale conversation history biases the model against the current task. Surfaces a discipline that Aider (/clear), Claude Code (/clear), CrewAI (memory=False, re-instantiate), and LangGraph (new thread_id, subgraph isolation) all encode separately but none name as a skill.
npx skills add agentsope/SkillAlchemy --skill agentsop-session-state-hygiene --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
What it does
Guides a coding-session hygiene process to manage AI tool context by recognizing symptoms of context bleed, deciding what to keep or drop, and restarting with a focused, clean window. It outlines concrete steps and several cut strategies (partial clear, save-and-clear, fresh thread, isolation, memory-off) and links to corresponding commands and components across tools.
How it works
- Activates when any bleed symptoms occur: topic shift, length/window warnings, or weird behavior. It requires naming the symptom in one line before acting.
- Saves what’s worth keeping: if there is a durable artifact (e.g., code changes, decisions, a one-paragraph summary), externalize to disk/git/clipboard before clearing.
- Applies a clear using a specified cut size chosen by the symptom: partial (OP-004), save+clear (OP-002), fresh (OP-003), isolate (OP-006), or memory-off (OP-007).
- Restarts with a focused, distilled state: first message uses the saved summary plus the current objective; do not paste the old transcript.
- Maintains evidence references from various tools to support decisions (e.g., aide/commands, langgraph/persistence).
When to use it
Active when any bleed symptoms are observed: topic shifts within a session, context window near ~25k tokens, or behavior inconsistent with prior corrections. Do not activate for a single LLM call, a one-shot query, or a brand-new session under 25k tokens behaving correctly.
What it can touch
The workflow involves commands and states across Aider, Claude Code, CrewAI, and LangGraph. It specifies actions like /clear, /drop <file>, update_state(messages=trimmed), and creating new thread_id or new Crew() instances. It references these tools and actions as part of the SOP steps, and notes when to save artifacts to disk/git/clipboard before clearing.
Caveats
Context bleed is mitigated by the smallest effective cut; clearing is not always the correct choice if crucial dependencies are not made durable. Persistent stores outside the transcript (e.g., CrewAI memory, LangGraph checkpointer) may retain state and require separate clearance. The SOP emphasizes not relying on prompt rewrites when history is polluted and details the need to externalize durable artifacts before clearing.
# Session-State Hygiene · SOP > One line: **context is signal; stale context is noise; clearing restores > signal.** A coding session is a sliding window of evidence. Early in a task > the window is pure signal. The longer it runs, the more dead ends, abandoned > plans, and superseded files accumulate — and at some point yesterday's good > context becomes today's bad bias. This skill is the discipline of noticing > that moment and acting on it with the smallest correct cut. > Source posture: every framework-specific claim is cited inline as > `[tool/topic]`. Resolve tags against `references/R1-source-evidence.md` (full > URLs) and `references/R2-tool-commands.md` (copy-pastable commands). --- ## 1. 何时激活 (When to Activate) Activate this skill the moment **any** of these fire — they are the symptoms of context bleed, not vague unease: - **Topic shift inside a session.** You finish feature A and start unrelated bug B in the same window/REPL/thread. The A-history is now pure noise for B. - **Length / window warning.** The tool reports the context window is N% full, or Aider's `/tokens` crosses **~25k** — the empirically observed point where "most models start to become distracted and b
- 1. 何时激活 (When to Activate)
- 2. 核心心智模型 (Core Mental Model)
- 2.1 The session window is evidence, and evidence decays
- 2.2 There is a measured distraction threshold
- 2.3 Clearing is a cut, and cuts have a size
- 2.4 The window is not the only state
- 3. SOP 工作流 (Standard Operating Procedure)
- Step 1 — Recognize (don't act yet)
- Step 2 — Save what's worth keeping (before any clear)
- Step 3 — Clear (smallest correct cut)
- Step 4 — Restart focused
- 4. 操作模型 (Operation Models)
- OP-001 · Detect context bleed
- OP-002 · Save-and-clear (same topic, polluted history)
What does the agentsop-session-state-hygiene skill do?
Decision protocol for managing the context/session state of an AI coding tool: when to /clear, when to keep context, and how to detect "context bleed" — the failure mode where stale conversation history biases the model against the current task. Surfaces a discipline that Aider (/clear), Claude Code (/clear), CrewAI (memory=False, re-instantiate), and LangGraph (new thread_id, subgraph isolation) all encode separately but none name as a skill.
How do I install it?
Run `npx skills add agentsope/SkillAlchemy --skill agentsop-session-state-hygiene --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From agentsope/SkillAlchemy, a repository with 255 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.