alirezarezvani/claude-skills / productivity/handoff/skills/session-handoff
session-handoff
VerifiedWrite a handoff document so a fresh session or another agent can pick up exactly where this one left off: goal, current state, decisions, next steps and the skills to load, referencing existing files instead of copying them, with secrets redacted before saving. Use whenever the user is ending a session, switching machines, running low on context, or asks for a handoff, a handoff doc, a 'pick up where we left off' summary, or to compact the conversation for next time. Saves to a location the user picks on first run (OS temp, home folder or per-project .handoff/) and can auto-load the latest handoff at the next session start.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 1.2 KB |
| SKILL.md | skill md | 9.6 KB |
| assets/example_handoff.md | markdown | 2.3 KB |
| references/configuration.md | markdown | 5.3 KB |
| references/deduplication_discipline.md | markdown | 4.5 KB |
| references/handoff_prompt.md | markdown | 4.3 KB |
| references/handoff_structure.md | markdown | 4.5 KB |
| references/redaction_checklist.md | markdown | 4.6 KB |
| scripts/cleanup.py | script | 5.1 KB |
| scripts/config_loader.py | script | 4.9 KB |
| scripts/handoff_self_check.py | script | 13.1 KB |
| scripts/handoff_template_generator.py | script | 7.9 KB |
| scripts/redaction_linter.py | script | 9.2 KB |
| scripts/setup.py | script | 9.6 KB |
| scripts/skill_recommender.py | script | 8.0 KB |
scripts/skill_recommender.py
View on GitHub#!/usr/bin/env python3
"""Skill recommender for the handoff doc.
Scans repo SKILL.md files, scores each against the user's goal text, and
returns the top 3-5 matches with a one-line *why*. Hard cap at 5 — Matt's
discipline: do not list 20 skills.
Stdlib-only.
"""
import argparse
import json
import re
import sys
from dataclasses import dataclass
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parent))
import config_loader # noqa: E402
# Domains the recommender knows about, ordered by typical relevance.
DOMAIN_DIRS = [
"productivity",
"engineering",
"engineering-team",
"marketing-skill",
"marketing",
"research",
"product-team",
"project-management",
"c-level-advisor",
"ra-qm-team",
"business-growth",
"business-operations",
"commercial",
"finance",
]
MAX_RESULTS = 5
MIN_SCORE = 1
@dataclass
class SkillCard:
slug: str
domain: str
title: str
description: str
path: Path
def _find_repo_root(start: Path) -> Path:
"""Walk parents and return the OUTERMOST dir containing CLAUDE.md.
Plugin folders also carry .claude-plugin/, so we cannot stop at the
first match — that would pin the recommender to a single plugin.
"""
cur = start.resolve()
outermost: Path | None = None
for parent in [cur, *cur.parents]:
if (parent / "CLAUDE.md").exists():
outermost = parent
if outermost is not None:
return outermost
for parent in [cur, *cur.parents]:
if (parent / ".claude-plugin").exists():
return parent
return start
def _parse_frontmatter(text: str) -> dict[str, str]:
if not text.startswith("---"):
return {}
end = text.find("\n---", 3)
if end == -1:
return {}
block = text[3:end].strip()
out: dict[str, str] = {}
key: str | None = None
buf: list[str] = []
for raw in block.splitlines():
if not raw.strip():
continue
m = re.match(r"^([A-Za-z0-9_\-]+)\s*:\s*(.*)$", raw)
if m and not raw.startswith(" ") and not raw.startswith("\t"):
if key is not None:
out[key] = " ".join(buf).strip().strip('"').strip("'")
key = m.group(1)
buf = [m.group(2)]
elif key is not None:
buf.append(raw.strip().strip('"').strip("'"))
if key is not None:
out[key] = " ".join(buf).strip().strip('"').strip("'")
return out
def _collect_skills(repo_root: Path, scope: str, current_domain: str | None) -> list[SkillCard]:
cards: list[SkillCard] = []
if scope == "off":
return cards
domains = DOMAIN_DIRS
if scope == "current_domain" and current_domain:
domains = [current_domain]
for d in domains:
domain_root = repo_root / d
if not domain_root.is_dir():
continue
for skill_md in domain_root.rglob("SKILL.md"):
if any(p.name in {"node_modules", ".git", "documentation"} for p in skill_md.parents):
continue
try:
text = skill_md.read_text(encoding="utf-8", errors="ignore")
except OSError:
continue
fm = _parse_frontmatter(text)
slug = fm.get("name") or skill_md.parent.name
description = fm.get("description") or ""
title = slug.replace("-", " ").title()
cards.append(
SkillCard(
slug=slug,
domain=d,
title=title,
description=description,
path=skill_md,
)
)
return cards
def _tokenize(text: str) -> list[str]:
return [t.lower() for t in re.findall(r"[A-Za-z][A-Za-z0-9_-]{2,}", text)]
_STOPWORDS = {
"the", "and", "for", "with", "from", "into", "that", "this", "next",
"session", "skill", "skills", "agent", "user", "should", "would",
"using", "use", "uses", "used", "make", "made", "have", "has",
"into", "your", "their", "them", "they", "where", "what", "when",
"who", "how", "why", "than", "then", "also", "more", "less",
}
def _score(card: SkillCard, goal_tokens: list[str], goal_set: set[str]) -> int:
if not goal_tokens:
return 0
haystack = f"{card.slug} {card.title} {card.description}".lower()
score = 0
for tok in goal_set:
if tok in _STOPWORDS:
continue
if len(tok) < 3:
continue
occurrences = haystack.count(tok)
score += occurrences
if tok in card.slug.lower():
score += 3
return score
def _short_description(description: str, limit: int = 140) -> str:
description = re.sub(r"\s+", " ", description).strip()
if len(description) <= limit:
return description
cut = description[:limit]
last_space = cut.rfind(" ")
if last_space > 80:
cut = cut[:last_space]
return cut.rstrip() + "..."
def recommend(goal: str, repo_root: Path, scope: str, current_domain: str | None) -> list[dict]:
cards = _collect_skills(repo_root, scope=scope, current_domain=current_domain)
goal_tokens = _tokenize(goal)
goal_set = set(goal_tokens)
scored: list[tuple[int, SkillCard]] = []
for c in cards:
s = _score(c, goal_tokens, goal_set)
if s >= MIN_SCORE:
scored.append((s, c))
scored.sort(key=lambda x: (-x[0], x[1].slug))
top = scored[:MAX_RESULTS]
out = []
for score, card in top:
out.append(
{
"slug": card.slug,
"domain": card.domain,
"score": score,
"why": _short_description(card.description),
"path": str(card.path.relative_to(repo_root)),
}
)
return out
def _format_markdown(results: list[dict], goal: str) -> str:
if not results:
return (
"_<!-- No matching skills found for this goal. Pick 3-5 manually. -->_"
)
lines = [f"_Recommendations for goal: {goal!r} (top {len(results)} of max {MAX_RESULTS})_", ""]
for r in results:
lines.append(f"- **{r['slug']}** ({r['domain']}) — {r['why']}")
return "\n".join(lines)
def main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(description="Recommend 3-5 skills for the next session.")
parser.add_argument("--goal", default="", help="Goal text to match against.")
parser.add_argument(
"--repo-root",
default="",
help="Repo root (defaults to autodetect from CWD).",
)
parser.add_argument(
"--scope",
choices=["all", "current_domain", "off"],
default=None,
help="Override config scope.",
)
parser.add_argument(
"--current-domain",
default=None,
help="Used when --scope current_domain (e.g. 'productivity').",
)
parser.add_argument("--json", action="store_true", help="Emit JSON.")
parser.add_argument("--sample", action="store_true", help="Run on a fixed goal and exit.")
args = parser.parse_args(argv)
if args.sample:
repo_root = _find_repo_root(Path(__file__).resolve())
results = recommend(
goal="implement redaction linter for handoff documents",
repo_root=repo_root,
scope="all",
current_domain=None,
)
if args.json:
print(json.dumps(results, indent=2))
else:
print(_format_markdown(results, "implement redaction linter for handoff documents"))
return 0
config = config_loader.load_config()
scope = args.scope or config.get("skill_recommendation_scope", "all")
repo_root = Path(args.repo_root).resolve() if args.repo_root else _find_repo_root(Path.cwd())
results = recommend(
goal=args.goal,
repo_root=repo_root,
scope=scope,
current_domain=args.current_domain,
)
if args.json:
print(json.dumps(results, indent=2))
else:
print(_format_markdown(results, args.goal or "(no goal)"))
return 0
if __name__ == "__main__":
sys.exit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |