capture-skill

name	capture-skill
description	Capture what was done in the current conversation as a repeatable, well-structured skill (SKILL.md). Interviews the user to clarify intent, scope, and edge cases before writing.
argument-hint	[skill-name] [brief description of what the skill does]

Capture a repeatable workflow from the current conversation and turn it into a properly structured skill. Interview the user to make sure we get it right the first time.

Input

The user may provide: $ARGUMENTS — an optional skill name and/or brief description of what the skill should do.

• If no arguments, analyze the current conversation to infer what should be captured, then confirm with the user.
• If arguments are provided, use them as a starting point but still ask clarifying questions.

Skill Anatomy Reference

Every skill lives in .claude/skills/{skill-name}/SKILL.md and follows this structure:

---
name: {skill-name}
description: {one-line description — this is what Claude sees when deciding whether to invoke the skill}
argument-hint: {example of what the user passes after the slash command}
---

{One-paragraph summary of what the skill does.}

## Input

{What $ARGUMENTS the skill expects, with examples and fallback behavior.}

## Process

### Phase 1: {Phase Name}
{Steps with numbered lists. Use AskUserQuestion when user input is needed.}

### Phase 2: {Phase Name}
{Continue as needed. Most skills have 3-6 phases.}

## Output

{What the skill produces — files created, state changed, summary shown to user.}

Key conventions:

• Phases are numbered and named. Each phase has a clear purpose.
• Use AskUserQuestion when the skill needs user input at runtime.
• Use $ARGUMENTS to reference what the user passes after the slash command.
• Skills can reference supporting files in the same directory (e.g., [template.md](template.md), [perspectives.md](perspectives.md)).
• The description field in frontmatter is critical — it determines when Claude auto-selects the skill. Be specific about triggers.
• The argument-hint field shows example arguments in help text.

Process

---

Phase 1: Understand What to Capture

1. Analyze the conversation context. Look at what was done in this conversation:

   • What task was performed?
   • What steps were followed?
   • What decisions were made along the way?
   • What tools were used?
   • What files were read, created, or modified?

2. Summarize your understanding to the user:

   Based on this conversation, it looks like the skill would: {summary}

   Is that right, or did you have something different in mind?

3. If $ARGUMENTS includes a skill name, use it. Otherwise, propose one based on the workflow.

---

Phase 2: Interview for Clarity

Ask clarifying questions to fill gaps. Don't ask everything at once — ask 2-3 questions at a time, grouped by theme. Provide your recommended answer for each question so the user can just confirm or correct.

Identity & Trigger:

• What should this skill be called? (propose a name if not provided)
• When should someone reach for this skill? What's the trigger phrase or situation?
• Write a draft description for the frontmatter — this is what determines auto-selection, so it needs to be precise.

Inputs & Arguments:

• What arguments does the skill take? Are any required vs optional?
• What happens if no arguments are provided? (discover from context, ask, or error?)
• Are there different modes of operation based on arguments?

Process & Variations:

• Are there decision points where the skill should branch?
• Are there edge cases or error conditions to handle?
• Should the skill ask for confirmation before taking action, or just do it?
• Are there steps that depend on the project context (language, framework, tooling)?

Output & Location:

• What does the skill produce? (files, git operations, terminal output, etc.)
• Where should output files go? Is there a naming convention?
• Should it show a summary or ask for approval before finalizing?

Scope:

• Where should this skill live?
  • Project skills (.claude/skills/ in the current repo) — for workflows specific to this project
  • User skills (~/.claude/skills/) — for workflows you want available everywhere
• Does the skill need supporting files (templates, checklists, reference docs)?

Skip questions where the answer is obvious from context. Move on once you have enough to write a solid first draft.

---

Phase 3: Draft the Skill

1. Write the SKILL.md draft following the anatomy reference above. Key principles:

   • Be prescriptive, not vague. Each phase should have concrete, numbered steps. A good skill reads like a runbook — someone (or Claude) following it step-by-step should produce consistent results.
   • Include the "why" for non-obvious steps. If a step exists because of a past mistake or a subtle requirement, note it briefly.
   • Handle the unhappy path. What happens if a file doesn't exist, a command fails, or the user says no? Don't leave gaps.
   • Don't over-engineer. If the workflow is simple, the skill should be simple. A 10-line skill that works is better than a 200-line skill that covers hypotheticals.
   • Use the right level of abstraction. Reference other skills (e.g., "use /write-to-grimoire") rather than inlining their logic. But don't create dependencies on skills that don't exist.

2. If supporting files are needed (templates, checklists, reference tables), draft those too.

3. Present the full draft to the user:

   Here's the skill draft:

   Location: {path to SKILL.md} Supporting files: {list, or "none"}

   {show the complete SKILL.md content}

   What would you change? I can revise before writing.

4. Wait for approval or revision requests. Iterate until the user is satisfied.

---

Phase 4: Write the Skill

1. Create the skill directory and files:

   • Write SKILL.md to the chosen location
   • Write any supporting files

2. Verify the skill is discoverable:

   • Confirm the file is in the right directory structure (.claude/skills/{name}/SKILL.md)
   • Confirm the frontmatter is valid (name, description, and optionally argument-hint)

3. Show a summary:

   Skill created: /{skill-name}

   • Location: {path}
   • Description: {description}
   • Arguments: {argument-hint or "none"}
   • Supporting files: {list or "none"}

   You can invoke it with /{skill-name} {example arguments if applicable}.

---

Output

A complete, well-structured skill in .claude/skills/{name}/SKILL.md (or ~/.claude/skills/{name}/SKILL.md for global skills), plus any supporting files. The skill follows established conventions and is immediately invocable.