# Keep Session

> >

- **Type:** Skill
- **Install:** `agentstack add skill-jesamkim-oh-my-skills-keep-session`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [jesamkim](https://agentstack.voostack.com/s/jesamkim)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jesamkim](https://github.com/jesamkim)
- **Source:** https://github.com/jesamkim/oh-my-skills/tree/main/my-skills/keep-session

## Install

```sh
agentstack add skill-jesamkim-oh-my-skills-keep-session
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# keep-session — Session continuity ledger (SESSION_LOG + dual bootstrap)

## Why this exists

Agent sessions die — crashes, context-window exhaustion, an accidental /clear, or the
user simply returning days later. Each time, a fresh session reconstructs project state
by grepping files and quizzing the user: slow, lossy, error-prone. This skill removes
that problem with a small file set:

| File | Role | Reader |
|---|---|---|
| `SESSION_LOG.md` | State ledger — snapshot, context digest, pointers, policies, log | The **agent** (next session) |
| `CLAUDE.md` | Bootstrap — auto-loaded on directory entry; forces reading the ledger first | Claude Code |
| `AGENTS.md` | Same bootstrap for harnesses that read AGENTS.md | Codex, Cursor, etc. |

The ledger is harness-neutral. Whatever coding agent the user continues with
(Claude Code → Codex or the reverse), the same ledger restores the same context —
which is why the bootstrap is installed into **both** CLAUDE.md and AGENTS.md with
identical content.

Key insight: even when a project already has human-facing docs (tracker, README), the
agent needs its own ledger. Human docs record *what happened*; an agent that must act
immediately needs **system pointers** (ticket/CRM IDs, Slack channel/draft IDs, email
thread subjects, scheduled-send times, external file paths) and the **exact state of
unfinished actions**. Those rarely survive in human docs.

**Language**: this skill file is English for token efficiency, but write the generated
artifacts (SESSION_LOG.md, bootstrap files) in the user's working language — the ledger
is read by future sessions serving the same user.

## Operation 1: init — set up

When the user asks to "set up a SESSION_LOG", "make this directory session-persistent",
etc.:

### 1-1. Identify the entry scenario, then capture state

init happens in two situations. Tell them apart from the directory contents and the
conversation history:

**(A) Mid-project** — the directory already has files/history.
Skim the files, and use the current conversation history if available, to reconstruct
the present state. Capture:

- In-flight work and next actions (unfinished items matter most)
- System IDs: ticket/CRM IDs, Slack channel/message/draft IDs, email thread
  subjects + send dates, external file paths (meeting notes, memory files), scheduled
  events (scheduled sends, meetings)
- Project-local policies (working rules the user has agreed to)
- The role of each file in the directory

If there is no conversation history and the files leave the state unclear, do not fill
gaps with guesses. Ask the user short, targeted questions (next action, pending external
events). If asking is impractical right now, add an **"Unresolved items" section** to the
SESSION_LOG listing the open questions — when a later session (or a user answer) resolves
one, fold it into the proper section, remove it from the list, and log the change. Mark
unresolved items as unverified in the snapshot too, so they never read as confirmed facts.

**(B) Day-one** — an empty (or nearly empty) directory being set up for upcoming work.
There is no past to reconstruct, so ask the user only for:

- A one-line description of the project (purpose, counterpart, deliverable)
- The first action

Start the snapshot/context sections minimal, and keep the file inventory and system
pointers as empty scaffolds — the full section structure stays in place and fills in
naturally through the update rules (Operation 2). The value of day-one setup is not the
content; it is that **the update habit runs from day one**.

### 1-2. Write SESSION_LOG.md

Use this six-section structure (battle-tested; keep it, though sections may be adapted
to the project). Write it in the user's working language:

```markdown
# SESSION_LOG — 

> **Purpose**: single-file context restore so any new agent session (Claude Code, Codex,
> etc.) can continue immediately.
> **Update rule**: after every meaningful action, append to the update log and refresh
> the snapshot.

## 1. Current-status snapshot (as of YYYY-MM-DD)

## 2. Context digest

## 3. File inventory (this directory)

## 4. System pointers (per-tool IDs/paths)

## 5. Policies & agreements (project-local)

## 6. Update log (newest first)
- **YYYY-MM-DD**: 
```

Section 4 (system pointers) is the highest-value section — invest there. Not "shared to
Slack" but "Slack draft `DrXXXXXXXX` → channel `CXXXXXXXXXX`, scheduled send Mon 09:00" —
precise enough for the next session to feed straight into tool calls.

### 1-3. Install the bootstrap — CLAUDE.md + AGENTS.md dual

Write the bootstrap content once, then install it **identically into both CLAUDE.md and
AGENTS.md**. Claude Code auto-loads CLAUDE.md; Codex/Cursor and others auto-load
AGENTS.md; both must exist for resume to work under any harness.

**Caution: if the target directory already has a CLAUDE.md or AGENTS.md, never
overwrite it.** Read the existing content and merge the bootstrap section in (append or
insert where it fits). Only create files that don't exist.

```markdown
#  — session bootstrap

## On session start (required)
1. **Read `SESSION_LOG.md` first** — the session-continuity ledger holding current
   status, system pointers, and in-flight actions
2. 

## While working (required)
- After every meaningful action (outbound communication, file create/edit, decision),
  **update SESSION_LOG.md immediately**:
  - refresh the "current-status snapshot"
  - append a dated entry to the "update log" (newest first)
  - add any new system IDs to "system pointers"
- If this bootstrap itself is edited, keep CLAUDE.md and AGENTS.md **in sync**
```

Keep the bootstrap and ledger wording harness-neutral — say "a new session" or "an agent
session", never "a CC session".

### 1-4. Record the first log entry

Log the creation of the SESSION_LOG itself as the first (or newest) update-log entry.

## How updates actually run: resident rule, not skill invocation

After init, the maintenance loop needs **no explicit skill invocation**. The bootstrap
installed into CLAUDE.md/AGENTS.md is a *resident rule*: it auto-loads on every session
start in that directory and instructs the session to update the ledger after each
meaningful action. The skill's job was planting that rule; from then on, every session —
any harness — self-maintains the ledger as a side effect of normal work. If a user asks
"do I need to run keep-session each time?", the answer is no.

**Explicit invocation after init = an audit pass.** When the user does invoke the skill
on an already-initialized directory, don't re-init — treat it as a request to find and
fix ledger gaps. The highest-yield blind spot, observed in practice: in **multi-session
orchestration** (e.g., a local session directing remote developer/reviewer sessions),
each session records *its own* work faithfully, but the orchestration context that
belongs to no single session — which external replies are pending and where each reply
slots into the code, why a remote agent is intentionally paused at an approval gate,
which session holds which role — ends up in **no one's ledger**. On an audit pass,
specifically hunt for such orchestrator-only context and write it into the snapshot.

Good moments to suggest (or for the user to request) an audit pass:

- Right after a phase transition that rewires who-does-what (dev-environment handoff,
  entering an external-wait state, a new agent joining)
- Before the user steps away for days — so any future session restores from the
  top block alone

## Operation 2: update — continuous refresh

Every session working in a directory where this skill is installed updates the
SESSION_LOG (per the bootstrap) at these moments:

- Outbound communication (email sent, Slack posted, ticket filed)
- File creation or significant edits
- Decisions/policy agreements with the user
- Scheduled events set up (scheduled sends, confirmed meetings)

Update principles:

1. **Snapshot is replaced; log is appended** — rewrite §1 as of "now" and bump the as-of
   date; never delete §6 entries, only stack new ones on top
2. **New IDs go into §4 immediately** — "later" means forgotten. The moment a draft ID,
   task ID, or conversation ID exists, record it
3. **Stay lean** — snapshot ~15 lines, log entries 1–3 lines. Details live in the
   human-facing doc (tracker etc.); the ledger holds pointers
4. **Update human docs in the same breath** — if a tracker exists, update both (division
   of labor: tracker = human-facing dashboard, SESSION_LOG = agent-facing ledger)

## Operation 3: resume — restore in a fresh session

When a new session opens in the directory, the bootstrap (CLAUDE.md for Claude Code,
AGENTS.md for Codex etc.) auto-loads and points at the SESSION_LOG. Resume order:

1. Read `SESSION_LOG.md` thoroughly — especially §1's top-priority action and §4 pointers
2. **Compare the as-of date with today** — a gap of days+ means the snapshot may be
   stale. For time-dependent items (scheduled sends, meetings), verify with tools
   whether they actually happened, then reflect the findings in the log. Never assume an
   elapsed event succeeded
3. Deepen with the human-facing main doc (tracker etc.)
4. Confirm with the user: "per the SESSION_LOG, current state is X, next action is Y" —
   then continue

If a pointer is broken (file moved, ID expired), don't silently skip it — fix the
SESSION_LOG and tell the user.

## What NOT to do

- Don't duplicate human-doc content wholesale into the ledger — pointers suffice
- Don't retro-edit log entries — correct mistakes with a new dated entry
- Don't overwrite an existing CLAUDE.md/AGENTS.md — merge only
- Don't put secrets or verbatim confidential content in the ledger — location pointers only

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [jesamkim](https://github.com/jesamkim)
- **Source:** [jesamkim/oh-my-skills](https://github.com/jesamkim/oh-my-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-jesamkim-oh-my-skills-keep-session
- Seller: https://agentstack.voostack.com/s/jesamkim
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.