mirror of
https://github.com/alirezarezvani/claude-skills.git
synced 2026-09-11 22:51:28 +00:00
1d066e0dec
Ships the three improvements judged most impactful in v1.1 design review:
1. SessionEnd hook (hooks/session_end.py)
Pairs with SessionStart. When a session ends with no handoff in the
last 30 minutes, prints a one-line reminder. Cannot prompt
interactively or block session end — surfaces text via stdout.
Disable per-session with HANDOFF_SESSIONEND=0. hooks.json updated to
wire both SessionStart and SessionEnd.
2. handoff_self_check.py — fidelity script (~300 LOC, stdlib-only)
Operationalizes handoff_prompt.md. Six checks:
- All 5 sections present
- Goal is non-empty and non-placeholder
- State-of-play bullets reference at least one artifact (commit hash,
PR/issue number, file path, URL)
- Open decisions are present (or explicit "- None.") when git is dirty
or has recent commits
- Skills to use: 3-5 entries, hard cap enforced
- Artifacts contain paths/URLs only, no inline content
Severity: high/medium/low. Strict mode exits 1 only on HIGH findings.
--sample fixture has 3 planted issues (2 high + 1 medium) and exits 1.
Canonical example_handoff.md passes clean (exit 0).
/cs:handoff command updated to run self-check between scaffold-fill
and redaction linter.
3. --refresh flag on handoff_template_generator.py
Reuses the most recent handoff in the configured save location
instead of creating a new file. Falls through to create-if-missing
when no existing handoff is found. Keeps the save location
uncluttered when work continues past the original handoff time;
ensures the SessionStart hook always loads the up-to-date version.
Version bump: 2.7.4 -> 2.7.5. Marketplace description and keywords
updated. README v1.1 section added. SKILL.md gains "Refreshing an
Existing Handoff" and "SessionEnd Reminder" subsections.
Verified:
- All 9 Python files compile clean
- self-check --sample correctly fails (3 findings, exit 1)
- self-check passes clean against assets/example_handoff.md (exit 0)
- --refresh finds the latest /tmp/handoff-*.md and prints its path
- SessionEnd hook prints the reminder when no recent handoff exists
- check_plugin_json.py + marketplace.json + hooks.json all parse
- Plugin audit re-run: structure 84.2 -> 86.0, quality 62.2 -> 63.0,
security PASS (0 critical, 0 high)
- Codex + Gemini sync re-ran clean
https://claude.ai/code/session_01KLhHBAfEDXdQMeRe6G8sRa
5.2 KiB
5.2 KiB
handoff (productivity)
Compact the current conversation into a handoff document for another agent to pick up.
A productivity-shaped handoff skill. Configurable save location (no project clutter), redaction enforcement, SessionStart auto-load, mandatory checklist for the agent. Five sections, three to five recommended skills, references not copies.
Inspired by Matt Pocock's handoff skill (MIT). Matt's seven sentences are preserved verbatim in SKILL.md. The wrapper around them — first-run setup, redaction linter, SessionStart hook, mandatory checklist, skill recommender — is original work in this repo.
Five must-haves shipped in v1.0.0
| # | Feature | Why |
|---|---|---|
| 1 | SessionStart hook auto-loads the latest handoff | Without this, the file is written but unread. The hook turns the artifact into an actual handoff. |
| 2 | First-run setup asks where to save | Avoids cluttering project folders. No pre-selected default — user picks explicitly on first run. |
| 3 | Mandatory checklist (handoff_prompt.md) |
Forces the agent to classify every topic (State / Decision / drop) rather than free-handing prose. |
| 4 | Redaction linter | Operationalizes Matt's redaction sentence with regex + whitelist marker + strict/warn modes. |
| 5 | mtime-guarded cleanup | Auto-cleanup never deletes a handoff the user edited as a working surface. |
v1.1 additions
| Feature | Why |
|---|---|
| SessionEnd reminder hook | Pairs with SessionStart. If a session ends without a recent handoff, prints a one-line reminder so the user doesn't lose context for next time. Disable with HANDOFF_SESSIONEND=0. |
Self-check script (handoff_self_check.py) |
Operationalizes the mandatory checklist. Flags empty Goal, State bullets that reference no artifact, missing Open decisions when git is dirty, too few/many Skills, inline content in Artifacts. Runs before the redaction linter. |
--refresh flag on the template generator |
Reuses the most recent handoff instead of creating a new file. Keeps the save location uncluttered when work continues past the original handoff. |
Install
This plugin lives at productivity/handoff/. Enable through your plugin manager. On first invocation of /cs:handoff, the skill will prompt:
Run setup now? (Y/n)
- Y — walks 5 questions and writes
~/.config/handoff/config.json. - N — uses defaults this run and never re-prompts (sentinel at
~/.config/handoff/.setup-declined).
Re-configure any time with /cs:handoff-setup.
Slash commands
| Command | Use |
|---|---|
/cs:handoff [goal] |
Generate the handoff doc. |
/cs:handoff-setup [--project] |
Configure (or reconfigure) save location, retention, redaction. |
Tooling
Stdlib-only Python. No external deps.
| Script | Purpose |
|---|---|
scripts/setup.py |
First-run Q&A. --reconfigure, --project, --decline, --sample. |
scripts/config_loader.py |
Shared helper. --show, --status, --sample. |
scripts/handoff_template_generator.py |
Writes the 5-section scaffold. --goal, --print-path-only, --sample. |
scripts/redaction_linter.py |
Scans for secrets/PII. --mode strict|warn|off, --json, --sample. |
scripts/skill_recommender.py |
Suggests 3-5 skills. --goal, --scope, --json, --sample. |
scripts/cleanup.py |
mtime-guarded retention cleanup. --dry-run, --json, --sample. |
Hooks
hooks/session_start.py (wired via hooks/hooks.json) — on every SessionStart, finds the most recent handoff in the configured save location and surfaces it as <handoff_from_previous_session> data. The next agent reads it as context, not instructions. Disable per-session with HANDOFF_SESSIONSTART=0.
References
| File | Topic |
|---|---|
references/handoff_prompt.md |
The mandatory checklist the agent walks before writing. |
references/handoff_structure.md |
The 5-section template with a worked example. |
references/deduplication_discipline.md |
Matt's no-duplication rule with concrete do-this-not-that pairs. |
references/redaction_checklist.md |
Regex patterns + manual review steps + whitelist mechanism. |
references/configuration.md |
Field-by-field config reference. |
Distinct from engineering/handoff/
| Aspect | productivity/handoff/ |
engineering/handoff/ |
|---|---|---|
| Primary audience | End-of-day session handoff, cross-machine handoff | Code/PR handoff |
| First-run setup | Yes (5 questions, configurable save location) | No (fixed mktemp) |
| Redaction enforcement | Yes (linter with strict/warn/off + inline whitelist) | No |
| SessionStart auto-load | Yes (hook + retention-aware) | No |
| Mandatory checklist | Yes (handoff_prompt.md, 6 steps) |
No |
| Retention cleanup | Yes (mtime-guarded) | No |
Both exist deliberately. The engineering version stays optimized for code/PR contexts. This one is for the broader daily routine.
Inspired by
Matt Pocock's handoff skill (MIT). The seven-sentence body of SKILL.md is Matt's, preserved verbatim. The wrapper is this repo's.
License
MIT.