From 3869cc9f74e44871a2693dfb6c94e229444c3c88 Mon Sep 17 00:00:00 2001
From: Gerald Onyango <gerald.onyango@gmail.com>
Date: Thu, 21 May 2026 16:25:47 -0400
Subject: [PATCH] feat: add handoff and write-a-skill skills

---
 skills/handoff/SKILL.md       | 34 +++++++++++++++++++
 skills/write-a-skill/SKILL.md | 63 +++++++++++++++++++++++++++++++++++
 2 files changed, 97 insertions(+)
 create mode 100644 skills/handoff/SKILL.md
 create mode 100644 skills/write-a-skill/SKILL.md

diff --git a/skills/handoff/SKILL.md b/skills/handoff/SKILL.md
new file mode 100644
index 0000000..7d9bea2
--- /dev/null
+++ b/skills/handoff/SKILL.md
@@ -0,0 +1,34 @@
+---
+name: handoff
+description: Compact the current conversation into a handoff document for another agent to pick up. Use when ending a session, switching context, or preparing work for the next session.
+---
+
+# Handoff
+
+Compact the current conversation into a handoff document for another agent to pick up.
+
+## Process
+
+1. Save to the user's OS temporary directory (not the workspace)
+2. Include a "suggested skills" section recommending skills for the next agent
+3. Reference existing artifacts (PRDs, plans, ADRs, issues, commits) by path or URL — don't duplicate
+4. Redact sensitive data: API keys, passwords, PII
+5. If the user provides arguments about next-session focus, tailor the document accordingly
+
+## Required Sections
+
+- **Summary**: What was accomplished this session
+- **Current State**: Branch, open files, what's working/broken
+- **Next Steps**: Prioritized list of what the next agent should do
+- **Key Context**: Architecture decisions, constraints, gotchas the next agent needs
+- **Suggested Skills**: Which skills the next agent should invoke
+- **References**: Paths/URLs to plans, docs, PRs, issues
+
+## Also Save to Prism
+
+If Prism MCP is available, also call `session_save_handoff` with:
+- project name
+- active branch
+- key context
+- open TODOs
+- last summary
diff --git a/skills/write-a-skill/SKILL.md b/skills/write-a-skill/SKILL.md
new file mode 100644
index 0000000..39ca4af
--- /dev/null
+++ b/skills/write-a-skill/SKILL.md
@@ -0,0 +1,63 @@
+---
+name: write-a-skill
+description: Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill.
+---
+
+# Writing Skills
+
+## Process
+
+1. **Gather requirements** — ask about: task/domain, use cases, need for scripts, reference materials
+2. **Draft the skill** — create SKILL.md (under 100 lines), split to REFERENCE.md if needed
+3. **Review with user** — present draft, iterate
+
+## Structure
+
+```
+skill-name/
+├── SKILL.md           # Main instructions (required, <100 lines)
+├── REFERENCE.md       # Detailed docs (if >100 lines)
+├── EXAMPLES.md        # Usage examples (if needed)
+└── scripts/           # Utility scripts (if deterministic ops needed)
+```
+
+## SKILL.md Template
+
+```md
+---
+name: skill-name
+description: Brief capability description. Use when [specific triggers].
+---
+
+# Skill Name
+
+## Quick start
+[Minimal working example]
+
+## Workflows
+[Step-by-step processes]
+
+## Advanced features
+[Link to REFERENCE.md if needed]
+```
+
+## Description Rules
+
+- Max 1024 chars, third person
+- First sentence: what it does
+- Second sentence: "Use when [triggers]"
+
+## When to Add Scripts
+
+Add when: operation is deterministic, same code generated repeatedly, errors need handling.
+
+## When to Split Files
+
+Split when: SKILL.md exceeds 100 lines, content has distinct domains, advanced features rarely needed.
+
+## Review Checklist
+
+- [ ] Description includes "Use when..." triggers
+- [ ] SKILL.md under 100 lines
+- [ ] No time-sensitive info
+- [ ] Concrete examples included