mirror of https://github.com/alirezarezvani/claude-skills.git synced 2026-09-07 08:26:02 +00:00

feat(productivity): derive caveman + grill-me + handoff from Matt Pocock (MIT)

Stream B PR 2 of 2 — three sibling productivity skills built using the
write-a-skill validators shipped in PR 1 (#642). The validators caught the
real issues (line counts, nesting depth, false-positive vocabulary in data
constants); the false positives are documented in the PR description.

Each skill follows the same wrapper pattern established in PR 1:
- Matt's SKILL.md content preserved verbatim per MIT license
- Attribution in README.md + plugin.json + SKILL.md frontmatter + every file footer
- 3 stdlib Python tools per skill (no LLM calls, embedded samples, JSON output)
- 3 in-depth references per skill (7-8 authoritative sources each)
- cs-* persona agent + /cs:* slash command
- Karpathy-coder validation: 100/100 complexity across all 9 tools

caveman (token-compression mode):
- Derived from https://github.com/mattpocock/skills/tree/main/skills/productivity/caveman
- Tools: caveman_compressor (apply Matt's rules deterministically, ~20-50%
  reduction on real prose, 75% upper bound), token_savings_estimator (chars/token
  heuristic + $/Mtok cost extrapolation), caveman_lint (detect banned vocab
  with code-block + exception-zone whitelisting)
- References: compression_principles (what to cut vs preserve, 8 sources),
  when_caveman_backfires (5 failure modes + auto-clarity exception, 7 sources)
- Agent: cs-caveman-mode (persistence-enforced)
- Command: /cs:caveman

grill-me (relentless plan interrogator):
- Derived from https://github.com/mattpocock/skills/tree/main/skills/productivity/grill-me
- Tools: decision_tree_extractor (6 branch kinds: intent/choice/open/tradeoff/
  dependency/question), question_generator (forcing questions with recommended
  answers + dependency-aware ordering), grill_session_tracker (JSON-backed
  state in ~/.grill_sessions/ for multi-day grills)
- References: forcing_question_patterns (6 patterns + soft-question anti-
  patterns, 8 sources), when_to_stop_grilling (3 stop conditions + 3 keep-going
  conditions + diminishing-returns test, 7 sources)
- Agent: cs-grill-master (one-question-at-a-time enforcer)
- Command: /cs:grill-me

handoff (conversation continuity generator):
- Derived from https://github.com/mattpocock/skills/tree/main/skills/productivity/handoff
- Tools: handoff_template_generator (5-section scaffold tailored to next-
  session focus across 5 emphases: deploy/review/debug/design/test/default,
  honors Matt's mktemp -t handoff-XXXXXX.md convention),
  artifact_deduplicator (detects PRD/ADR/issue/commit/long-code-block
  duplication with reference suggestions), skill_recommender (matches handoff
  content to 14 skills in this repo, ranked by signal strength)
- References: handoff_structure (5 sections + tailoring logic, 7 sources),
  deduplication_discipline (5 categories of duplication + fix patterns,
  7 sources), next_session_skill_matching (recommender logic + ranking,
  7 sources)
- Agent: cs-handoff-author (no-duplication-tolerated)
- Command: /cs:handoff with argument hint per Matt's convention

Karpathy-coder validation (full sweep):
- complexity_checker: 100/100 across all 9 tools (0 findings)
- assumption_linter: documented false positives only (caveman tools contain
  banned-vocabulary STRINGS as DATA to detect/remove; handoff tools contain
  intentionally-bad fixture text in SAMPLE_HANDOFF_BAD; skill_recommender
  contains "refactor"/"complexity" as recommendation keywords)
- All 9 tools: PASS text + PASS JSON output (exit 1 on caveman_lint +
  artifact_deduplicator is intentional — embedded samples are designed to
  FAIL the respective check)
- 9 references cite 7-8 authoritative sources each

Write-a-skill validators (the meta-skill, dogfooded):
- description_validator: PASS on all 3 SKILL.md (all are <=1024 chars + third
  person + "Use when" trigger + action verb in first sentence)
- structure_validator: PASS on all 3 (folders correct, SKILL.md <100 lines,
  references one level deep, no circular refs)
- review_checklist_runner: PASS on all 3 (all 6 of Matt's checklist items)
- SKILL.md line counts: 67 (caveman) / 56 (grill-me) / 39 (handoff) — all
  under Matt's 100-line ceiling

34 files, 4,033 insertions. License: MIT (matching Matt's upstream).

Closes the Stream B Matt Pocock productivity skills derivation:
- write-a-skill (PR #642, merged)
- caveman + grill-me + handoff (this PR)

https://claude.ai/code/session_01VFreMf7XLBqMgjsrG4wSYe

2026-05-13 21:50:40 +00:00

2.2 KiB

Raw Permalink Blame History

handoff

Conversation-handoff document generator. Saves the current state of a conversation so a fresh agent can pick up the work cleanly.

Attribution

Derived from Matt Pocock's handoff (MIT). Matt's no-duplication discipline preserved verbatim — handoff docs reference existing artifacts by path/URL, never duplicate them.

What this adds on top of Matt's original

Addition	Where	Why
3 stdlib Python tools	`skills/handoff/scripts/`	Template generator (tailored to next-session focus), artifact deduplicator (find references that should replace inline content), skill recommender (which skills next session needs)
3 in-depth references (5+ sources each)	`skills/handoff/references/`	Handoff structure · Deduplication discipline · Skill matching for next session
cs-handoff-author persona agent	`agents/cs-handoff-author.md`	Continuity-focused handoff author with hard rule against duplication
`/cs:handoff` slash command	`commands/cs-handoff.md`	One-shot handoff generation with argument hint

Matt's original (preserved)

"Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save it to a path produced by mktemp -t handoff-XXXXXX.md (read the file before you write to it). Suggest the skills to be used, if any, by the next session. Do not duplicate content already captured in other artifacts (PRDs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead. If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly."

Quick start

# Generate a handoff template scaffold tailored to next-session focus
python skills/handoff/scripts/handoff_template_generator.py --next-focus "ship PR 2"

# Detect artifacts in a handoff draft that could be replaced by references
python skills/handoff/scripts/artifact_deduplicator.py path/to/draft-handoff.md

# Recommend skills for the next session based on handoff content
python skills/handoff/scripts/skill_recommender.py path/to/handoff.md

License

MIT (matching Matt's upstream).

2.2 KiB Raw Permalink Blame History