Handoff Skill

Quick Ref: Create structured handoff for session continuation. Output: .agents/handoff/YYYY-MM-DD-<topic>.md + continuation prompt.

YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

Create a handoff document that enables seamless session continuation.

Execution Steps

Given /handoff [topic]:

Step 1: Create Output Directory

mkdir -p .agents/handoff

Step 2: Identify Session Context

If topic provided: Use it as the handoff identifier.

If no topic: Derive from recent activity:

# Recent commits
git log --oneline -5 --format="%s" | head -1

# Check current issue
bd current 2>/dev/null | head -1

# Check ratchet state
ao ratchet status 2>/dev/null | head -3

Use the most descriptive source as the topic slug.

Topic slug format: 2-4 words, lowercase, hyphen-separated (e.g., auth-refactor, api-validation). Fallback: If no good topic found, use session-$(date +%H%M) (e.g., session-1430).

Step 3: Gather Session Accomplishments

Review what was done this session:

# Recent commits this session (last 2 hours)
git log --oneline --since="2 hours ago" 2>/dev/null

# Recent file changes
git diff --stat HEAD~5 2>/dev/null | head -20

# Research produced
ls -lt .agents/research/*.md 2>/dev/null | head -3

# Plans created
ls -lt .agents/plans/*.md 2>/dev/null | head -3

# Issues closed
bd list --status closed --since "2 hours ago" 2>/dev/null | head -5

Step 4: Identify Pause Point

Determine where we stopped:

1. What was the last thing done?
2. What was about to happen next?
3. Were we mid-task or between tasks?
4. Any blockers or decisions pending?

Check for in-progress work:

bd list --status in_progress 2>/dev/null | head -5

Step 5: Identify Key Files to Read

List files the next session should read first:

• Recently modified files (core changes)
• Research/plan artifacts (context)
• Any files mentioned in pending issues

# Recently modified
git diff --name-only HEAD~5 2>/dev/null | head -10

# Key artifacts
ls .agents/research/*.md .agents/plans/*.md 2>/dev/null | tail -5

Step 6: Write Handoff Document

Write to: .agents/handoff/YYYY-MM-DD-<topic-slug>.md (use date +%Y-%m-%d)

# Handoff: <Topic>

**Date:** YYYY-MM-DDTHH:MM:SSZ
**Session:** <brief session description>
**Status:** <Paused mid-task | Between tasks | Blocked on X>

---

## What We Accomplished This Session

### 1. <Accomplishment 1>

<Brief description with file:line citations>

**Files changed:**
- `path/to/file.py` - Description

### 2. <Accomplishment 2>

...

---

## Where We Paused

<Clear description of pause point>

**Last action:** <what was just done>
**Next action:** <what should happen next>
**Blockers (if any):** <anything blocking progress>

---

## Context to Gather for Next Session

1. <Context item 1> - <why needed>
2. <Context item 2> - <why needed>

---

## Questions to Answer

1. <Open question needing decision>
2. <Clarification needed>

---

## Files to Read

Priority files (read first)

path/to/critical-file.py .agents/research/YYYY-MM-DD-topic.md

Secondary files (for context)

path/to/related-file.py

### Step 7: Write Continuation Prompt

**Write to:** `.agents/handoff/YYYY-MM-DD-<topic-slug>-prompt.md` (use `date +%Y-%m-%d`)

```markdown
# Continuation Prompt for New Session

Copy/paste this to start the next session:

---

## Context

<2-3 sentences describing the work and where we paused>

## Read First

1. The handoff doc: `.agents/handoff/YYYY-MM-DD-<topic-slug>.md`
2. <Other critical files>

## What I Need Help With

<Clear statement of what the next session should accomplish>

## Key Files

Open Questions

1. <Question 1>
2. <Question 2>

---

<Suggested skill to invoke, e.g., "Use /implement to continue">

### Step 8: Extract Learnings (Optional)

If significant learnings occurred this session, also run post-mortem:

```bash
# Check if post-mortem skill should be invoked
# (if >3 commits or major decisions made)
git log --oneline --since="2 hours ago" 2>/dev/null | wc -l

If ≥3 commits: Suggest running /post-mortem --quick to extract learnings. If <3 commits: Handoff alone is sufficient; learnings are likely minimal.

Step 9: Report to User

Tell the user:

1. Handoff document location
2. Continuation prompt location
3. Summary of what was captured
4. Suggestion: Copy the continuation prompt for next session
5. If learnings detected, suggest /post-mortem --quick

Output completion marker:

<promise>DONE</promise>

If no context to capture (no commits, no changes):

<promise>EMPTY</promise>
Reason: No session activity found to hand off

Example Output

Handoff created:
  .agents/handoff/20260131T143000Z-auth-refactor.md
  .agents/handoff/20260131T143000Z-auth-refactor-prompt.md

Session captured:
- 5 commits, 12 files changed
- Paused: mid-implementation of OAuth flow
- Next: Complete token refresh logic

To continue: Copy the prompt from auth-refactor-prompt.md

<promise>DONE</promise>

Key Rules

• Capture state, not just summary - next session needs to pick up exactly where we left off
• Identify blockers clearly - don't leave the next session guessing
• List files explicitly - paths, not descriptions
• Write the continuation prompt - make resumption effortless
• Cite everything - file:line for all references

Integration with /post-mortem

Handoff captures state for continuation. Post-mortem captures learnings for the flywheel (full knowledge lifecycle).

For a clean session end:

/handoff              # Capture state for continuation
/post-mortem --quick  # Extract learnings for future

Both should be run when ending a productive session.

Without ao CLI

If ao CLI not available:

1. Skip the ao ratchet status check in Step 2
2. Step 8 retro suggestion still works (uses git commit count)
3. All handoff documents are still written to .agents/handoff/
4. Knowledge is captured for future sessions via handoff, just not indexed

---

Examples

Paused Mid-Implementation

User says: /handoff (after working on OAuth flow for 2 hours, need to stop)

What happens:

1. Agent detects recent commits (5 commits in last 2 hours, auth-related)
2. Agent checks in-progress work with bd list (issue #42 still open)
3. Agent identifies pause point: "Completed token generation, about to start refresh logic"
4. Agent lists key files: auth.go, token.go, research doc, plan doc
5. Agent writes handoff document with accomplishments and pause state
6. Agent writes continuation prompt with clear next action
7. Agent checks commits (5) and suggests running /post-mortem --quick to extract learnings

Result: Handoff captures state, continuation prompt ready, post-mortem suggested.

Between Tasks, Clean State

User says: /handoff (just closed issue #40, about to start #41 next session)

What happens:

1. Agent detects 1 commit (closed issue #40), no pending changes
2. Agent identifies pause point: "Between tasks. Last: closed #40 (fixed rate limiting). Next: start #41 (add JWT refresh)"
3. Agent lists files from #40 (middleware.go, config.go)
4. Agent writes handoff with accomplishment summary and next-task preview
5. Agent writes continuation prompt with /implement #41 suggestion
6. Agent skips post-mortem suggestion (<3 commits)

Result: Handoff captures clean boundary, continuation is simple.

Auto-Derived Topic

User says: /handoff (no topic provided, agent derives from commits)

What happens:

1. Agent reads recent commits: "feat: add rate limiting", "fix: token expiry"
2. Agent derives topic slug: "rate-limiting" (from most recent commit)
3. Agent creates handoff files with derived topic in filename
4. Agent reports: "Handoff created: .agents/handoff/20260213T143000Z-rate-limiting.md"

Result: Topic auto-derived from git history, no user input needed.

---

Troubleshooting

Problem	Cause	Solution
"No session activity found to hand off"	No commits, no file changes detected	Expected for idle sessions. Nothing to hand off. Start new work or skip handoff.
Handoff files not written	.agents/handoff/ directory does not exist or not writable	Run mkdir -p .agents/handoff or check directory permissions
Topic slug is generic "session-1430"	No descriptive commits or issues to derive topic fro how to use handoff CursorClaude CodeClineCodexWindsurfGooseGitHub CopilotVS CodeGemini CLIKiloOpencodeKimi CLIRoo ClineAiderContinueZedBolt.newLovablev0Replit AgentSweepSmol DeveloperDevinCavemanAmpAntigravity How to use handoff on Cursor AI-first code editor with Composer 1 Prerequisites Before installing skills in Cursor, ensure your development environment meets these requirements: ›Cursor installed and configured on your development machine ›Node.js version 16.0+ with npm package manager (verify with node --version) ›Active project directory or workspace where you want to add handoff 2 Execute installation command Execute the skills CLI command in your project's root directory to begin installation: $npx skills add https://github.com/boshu2/agentops --skill handoffcopy The skills CLI fetches handoff from GitHub repository boshu2/agentops and configures it for Cursor. 3 Select Cursor when prompted The CLI will show a list of available agents. Use arrow keys to navigate and space to select Cursor: ◆ Which agents do you want to install to? │ │ ── Universal (.agents/skills) ── always included ──── │ • Amp │ • Antigravity │ • Cline │ • Codex │ ●Cursor(selected) │ • Cursor │ • Windsurf 4 Verify installation Confirm successful installation by checking the skill directory location: .cursor/skills/handoff Reload or restart Cursor to activate handoff. Access the skill through slash commands (e.g., /handoff) or your agent's skill management interface. ⚠ Security & Verification Notice We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use. Skills execute code in your development environment. Always verify the publisher's identity, review recent commits, and test in isolated environments before production deployment. Additional Resources ›View source code on GitHub›Skills CLI documentation›Learn more about Cursor›What are agent skills? List & Monetize Your Skill Submit your Claude Code skill and start earning GET_STARTED → Use Cases▌ User Story & Requirements Generation Create detailed user stories, acceptance criteria, and feature specs Example Generate user stories for 'password reset feature' with acceptance criteria, edge cases, and test scenarios ✓ Reduce spec writing time by 50%, ensure comprehensive coverage Competitive Analysis Research competitors, compare features, identify gaps Example Analyze 5 competitor products, create feature comparison matrix, suggest differentiation opportunities ✓ Complete competitive research in 2 hours instead of 2 days Roadmap Prioritization Evaluate features using frameworks (RICE, ICE, Kano) and create prioritized backlogs Example Score 20 feature ideas using RICE framework, generate prioritized roadmap with rationale ✓ Make data-driven prioritization decisions faster Stakeholder Communication Draft PRDs, status updates, and stakeholder presentations Example Create executive summary of Q3 roadmap, monthly progress report, feature launch announcement ✓ Save 3-5 hours/week on communication overhead Implementation Guide▌ Prerequisites ›Claude Desktop or compatible AI client ›Access to product documentation and roadmap tools (Jira, Notion, etc.) ›Understanding of product management frameworks (RICE, Jobs-to-be-Done, etc.) ›Stakeholder contact information and communication channels Time Estimate 30-60 minutes to see productivity improvements Installation Steps 1.Install product management skill 2.Start with user story generation for known feature 3.Progress to competitive analysis: research 2-3 competitors 4.Use for roadmap prioritization: apply RICE/ICE scoring 5.Draft stakeholder communications and refine based on feedback 6.Build template library for recurring PM tasks 7.Share effective prompts with product team Common Pitfalls ⚠Not validating competitive research—verify facts before sharing ⚠Accepting user stories without involving engineering team ⚠Over-relying on frameworks without qualitative judgment ⚠Not customizing outputs to company culture and communication style ⚠Skipping stakeholder validation of generated requirements Best Practices▌ ✓ Do +Validate research and competitive analysis with real data +Collaborate with engineering when generating technical requirements +Customize frameworks and templates to your company context +Use skill for first drafts, refine with stakeholder input +Document successful prompt patterns for PM tasks +Combine AI efficiency with human judgment and intuition ✗ Don't −Don't publish competitive analysis without fact-checking −Don't finalize user stories without engineering review −Don't make prioritization decisions solely on AI scoring −Don't skip customer validation of generated requirements −Don't ignore company-specific context and culture 💡 Pro Tips ★Provide context: company goals, constraints, customer feedback ★Ask for alternatives: 'Show 3 ways to prioritize this roadmap' ★Request stakeholder-specific formatting: 'Executive summary vs. engineering spec' ★Use skill for 70% generation + 30% customization to company needs When to Use This▌ ✓ Use When Use for user story writing, competitive research, roadmap prioritization, stakeholder communication, and PRD drafting. Best for reducing repetitive documentation and research work. ✗ Avoid When Avoid for strategic product vision (requires deep customer empathy), pricing decisions (needs market and financial expertise), or when face-to-face customer discovery is more valuable than speed. Learning Path▌ 1Basic: user stories, feature specs, status updates 2Intermediate: competitive analysis, prioritization frameworks, PRDs 3Advanced: product strategy, go-to-market planning, OKR setting 4Expert: product vision, market positioning, business model innovation Discussion Product Hunt–style comments (not star reviews) post comment No comments yet — start the thread. general reviews Ratings 4.7★★★★★41 reviews ★★★★★Aditi Mehta· Dec 16, 2024 Registry listing for handoff matched our evaluation — installs cleanly and behaves as described in the markdown. ★★★★★Yash Thakker· Dec 12, 2024 handoff fits our agent workflows well — practical, well scoped, and easy to wire into existing repos. ★★★★★Kaira Bhatia· Dec 8, 2024 Keeps context tight: handoff is the kind of skill you can hand to a new teammate without a long onboarding doc. ★★★★★Kabir Anderson· Nov 27, 2024 handoff has been reliable in day-to-day use. Documentation quality is above average for community skills. ★★★★★Yuki Diallo· Nov 11, 2024 Useful defaults in handoff — fewer surprises than typical one-off scripts, and it plays nicely with `npx skills` flows. ★★★★★Amelia Perez· Nov 7, 2024 handoff fits our agent workflows well — practical, well scoped, and easy to wire into existing repos. ★★★★★Dhruvi Jain· Nov 3, 2024 Registry listing for handoff matched our evaluation — installs cleanly and behaves as described in the markdown. ★★★★★Diya Reddy· Oct 26, 2024 We added handoff from the explainx registry; install was straightforward and the SKILL.md answered most questions upfront. ★★★★★Oshnikdeep· Oct 22, 2024 handoff reduced setup friction for our internal harness; good balance of opinion and flexibility. ★★★★★Sofia Desai· Oct 18, 2024 Solid pick for teams standardizing on skills: handoff is focused, and the summary matches what you get after install. showing 1-10 of 41 prev1 / 5next bookmarkshare