agentleFS
imMamdouhaboammarimMamdouhaboammar/kaku-chatgpt-harness/.agents/skills/session-handoff/SKILL.md

session-handoff

Skill0 starsChanged 4 months agoMITView on GitHub

Creates comprehensive handoff documents for seamless AI agent session transfers. Triggered when: (1) user requests handoff/memory/context save, (2) context window approaches capacity, (3) major task milestone completed, (4) work session ending, (5) user says 'save state', 'create handoff', 'I need to pause', 'context is getting full', (6) resuming work with 'load handoff', 'resume from', 'continue where we left off'. Proactively suggests handoffs after substantial work (multiple file edits, complex debugging, architecture decisions). Solves long-running agent context exhaustion by enabling fresh agents to continue with zero ambiguity.

149 other projects use a version of this, 3 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use ascii-diagram, research-fleet and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • SethGammonSkill

    ascii-diagram

    Generate perfectly aligned ASCII diagrams — architecture, flow, sequence, box-and-arrow. Uses a programmatic character-grid approach so alignment is guaranteed by math, not token prediction. Includes post-render verification.

    Also in 4 projects that use this

  • SethGammonSkill

    research-fleet

    Parallel research using Fleet wave mechanics. Spawns multiple scout agents, each investigating a different angle of the same question. Findings are compressed between waves. Produces a unified research brief from multiple independent perspectives.

    Also in 3 projects that use this

  • vicoa-aiSkill

    live-preview

    Start a local app in the current user project, expose it through a tunnel, and return preview details in structured Markdown. Use when the user asks for a preview URL, public URL, shareable localhost, mobile/web preview, or tunnel setup.

    Also in 4 projects that use this

  • Dizzy-TenSkill

    bug-diagnosis

    Diagnose bugs and product issues without modifying code. Use when the user explicitly invokes $bug-diagnosis or asks for diagnosis, root-cause analysis, issue classification, or fix strategy for code bugs, failing tests, configuration/dependency problems, deployment issues, performance regressions, data anomalies, or frontend/user-experience problems described through screenshots, annotations, logs, errors, or natural-language reports. Prioritize analysis and recommendations only; do not edit files.

    Also in 4 projects that use this

  • botlearn-aiSkill

    doc-gen

    Also in 4 projects that use this

  • flyingobsidianSkill

    terminology

    Read a codebase, find terminology, create/update definitions into a markdown document.

    Also in 3 projects that use this

  • +1 more from SethGammon

The file

Show its rules and text

We split this skill into the rules it gives an agent

19 rules. 0 are common, 17 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 125 edited versions we read keep these.

  • 17

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Follow: CREATE Workflow below

    line 15
  2. Distinctive:

    Follow: RESUME Workflow below

    line 18
  3. Distinctive:

    Proactive suggestion?: After substantial work (5+ file edits, complex debugging, major decisions), suggest:

    line 20
  4. Distinctive:

    Run the smart scaffold script to create a pre-filled handoff document:

    line 27
  5. Very specific:

    Create .claude/handoffs/ directory if needed

    line 41
  6. Distinctive:

    Add handoff chain links if continuing from previous

    line 44
  7. Distinctive:

    Use the template structure in references/handoff-template.md for guidance.

    line 56
  8. Distinctive:

    Run the validation script to check completeness and security:

    line 60
  9. Distinctive:

    Before loading, check how current the handoff is:

    line 97
  10. Distinctive:

    STALE: Verify context carefully before resuming

    line 106
  11. Very specific:

    VERY_STALE: Consider creating a fresh handoff

    line 107
  12. Distinctive:

    Read the relevant handoff document completely before taking any action.

    line 118
  13. Distinctive:

    If handoff is part of a chain (has "Continues from" link), also read the linked previous handoff for full context.

    line 120
  14. Distinctive:

    Follow the checklist in references/resume-checklist.md:

    line 124
  15. Distinctive:

    Verify project directory and git branch match

    line 126
  16. Distinctive:

    Check if blockers have been resolved

    line 127
  17. Distinctive:

    Start with "Immediate Next Steps" item #1 from the handoff document.

    line 134
  18. Distinctive:

    Add new discoveries to relevant sections

    line 145
  19. Distinctive:

    When resuming from a chain, read the most recent handoff first, then reference predecessors as needed.

    line 165

“Common” is measured: kept by at least 6 in 10 of the 125 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Handoff

Creates comprehensive handoff documents that enable fresh AI agents to seamlessly continue work with zero ambiguity. Solves the long-running agent context exhaustion problem.

Mode Selection

Determine which mode applies:

Creating a handoff? User wants to save current state, pause work, or context is getting full.

  • Follow: CREATE Workflow below

Resuming from a handoff? User wants to continue previous work, load context, or mentions an existing handoff.

  • Follow: RESUME Workflow below

Proactive suggestion? After substantial work (5+ file edits, complex debugging, major decisions), suggest:

"We've made significant progress. Consider creating a handoff document to preserve this context for future sessions. Say 'create handoff' when ready."

CREATE Workflow

Step 1: Generate Scaffold

Run the smart scaffold script to create a pre-filled handoff document:

python scripts/create_handoff.py [task-slug]

Example: python scripts/create_handoff.py implementing-user-auth

For continuation handoffs (linking to previous work):

python scripts/create_handoff.py "auth-part-2" --continues-from 2024-01-15-auth.md

The script will:

  • Create .claude/handoffs/ directory if needed
  • Generate timestamped filename
  • Pre-fill: timestamp, project path, git branch, recent commits, modified files
  • Add handoff chain links if continuing from previous
  • Output file path for editing

Step 2: Complete the Handoff Document

Open the generated file and fill in all [TODO: ...] sections. Prioritize these sections:

  1. Current State Summary - What's happening right now
  2. Important Context - Critical info the next agent MUST know
  3. Immediate Next Steps - Clear, actionable first steps
  4. Decisions Made - Choices with rationale (not just outcomes)

Use the template structure in references/handoff-template.md for guidance.

Step 3: Validate the Handoff

Run the validation script to check completeness and security:

python scripts/validate_handoff.py <handoff-file>

The validator checks:

  • No [TODO: ...] placeholders remaining
  • Required sections present and populated
  • No potential secrets detected (API keys, passwords, tokens)
  • Referenced files exist
  • Quality score (0-100)

Do not finalize a handoff with secrets detected or score below 70.

Step 4: Confirm Handoff

Report to user:

  • Handoff file location
  • Validation score and any warnings
  • Summary of captured context
  • First action item for next session

RESUME Workflow

Step 1: Find Available Handoffs

List handoffs in the current project:

python scripts/list_handoffs.py

This shows all handoffs with dates, titles, and completion status.

Step 2: Check Staleness

Before loading, check how current the handoff is:

python scripts/check_staleness.py <handoff-file>

Staleness levels:

  • FRESH: Safe to resume - minimal changes since handoff
  • SLIGHTLY_STALE: Review changes, then resume
  • STALE: Verify context carefully before resuming
  • VERY_STALE: Consider creating a fresh handoff

The script checks:

  • Time since handoff was created
  • Git commits since handoff
  • Files changed since handoff
  • Branch divergence
  • Missing referenced files

Step 3: Load the Handoff

Read the relevant handoff document completely before taking any action.

If handoff is part of a chain (has "Continues from" link), also read the linked previous handoff for full context.

Step 4: Verify Context

Follow the checklist in references/resume-checklist.md:

  1. Verify project directory and git branch match
  2. Check if blockers have been resolved
  3. Validate assumptions still hold
  4. Review modified files for conflicts
  5. Check environment state

Step 5: Begin Work

Start with "Immediate Next Steps" item #1 from the handoff document.

Reference these sections as you work:

  • "Critical Files" for important locations
  • "Key Patterns Discovered" for conventions to follow
  • "Potential Gotchas" to avoid known issues

Step 6: Update or Chain Handoffs

As you work:

  • Mark completed items in "Pending Work"
  • Add new discoveries to relevant sections
  • For long sessions: create a new handoff with --continues-from to chain them

Handoff Chaining

For long-running projects, chain handoffs together to maintain context lineage:

handoff-1.md (initial work)
    ↓
handoff-2.md --continues-from handoff-1.md
    ↓
handoff-3.md --continues-from handoff-2.md

Each handoff in the chain:

  • Links to its predecessor
  • Can mark older handoffs as superseded
  • Provides context breadcrumbs for new agents

When resuming from a chain, read the most recent handoff first, then reference predecessors as needed.

Storage Location

Handoffs are stored in: .claude/handoffs/

Naming convention: YYYY-MM-DD-HHMMSS-[slug].md

Example: 2024-01-15-143022-implementing-auth.md

Resources

scripts/

ScriptPurpose
create_handoff.py [slug] [--continues-from <file>]Generate new handoff with smart scaffolding
list_handoffs.py [path]List available handoffs in a project
validate_handoff.py <file>Check completeness, quality, and security
check_staleness.py <file>Assess if handoff context is still current

references/

  • handoff-template.md - Complete template structure with guidance
  • resume-checklist.md - Verification checklist for resuming agents

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.