extract-skill

Files (1)

• SKILL.md

SKILL.md (first lines)

# Extract Skill

Backwards-compile a reusable SKILL.md from a worked example. Distinct from `new-skill` (which creates a skill forward from a description) — this one **synthesizes from observed conversation**: what we actually did, why we made the calls we made, what edge cases we hit, what the hard rules turned out to be.

The product is a SKILL.md following Daniel's conventions (frontmatter with name + description-with-trigger-phrases, then a body with When-to-use, Steps, Gotchas, Hard rules, Counterparts).

## When to use

- The user just walked through a non-trivial procedure and says "let's extract this as a skill"
- Late in a long session where the user wants to bottle the process before clearing context
- After a worked example surfaces enough decision points and edge cases that re-deriving them next time would be wasteful
- When `log-session` is being run and the procedural meat is worth promoting from a one-off log entry to a reusable skill

If the procedure is fully captured by an existing skill (e.g., the user is just walking through `migrate-loose-skill` and there's nothing new), don't extract — point at the existing skill instead.

## Steps

### 1. Identify the procedure

Scan the conversation. Look for:

- A clear **goal** the user articulated (often phrased as "let's…", "I want to…", "we need to…")
- A sequence of **steps** that were taken to reach it (tool calls, file edits, decisions confirmed)
- **Decision points** where the user picked between options (these become "ask before X" rules in the skill)
- **Edge cases** that emerged (these become Gotchas)
- **Hard rules** that crystallized (things the user said "don't do that" or "always do that")

If the conversation has multiple distinct procedures interleaved, ask:

> I see [N] candidate procedures: [A], [B], [C]. Which one to extract? (or all, as separate skills)

### 2. Draft the SKILL.md

Use this skeleton. Fill from observed conversation, not from imagination:

```markdown
---
name: <kebab-case-name>
description: <one paragraph: what the skill does, when to invoke it, with the ACTUAL trigger phrases the user uses or would naturally use — drawn from the conversation, not invented>
---

# <Title Case Name>

<One-paragraph framing: what the skill does and why it exists. Distinguish from any neighboring skills.>

## When to use

- <bullet — concrete trigger condition from the conversation>
- <bullet — another>
- <skip / negation rule if relevant: "don't use this when X — use Y instead">

## Steps

### 1. <action verb + object>

<concrete what-to-do, with code blocks where applicable>

### 2. <next>

…

(As many steps as the procedure had. Don't pad — but don't compress past the point where the next session could re-derive what to do.)

## Gotchas

<bugs / surprises / dead-ends from the actual session — each as a numbered item with the symptom and the fix or workaround>

1. **<symptom>** — <what causes it, what to do instead>

## Hard rules

<crystallized "always do X" / "never do Y" — drawn from user corrections or explicit statements during the session>

- **<rule>**
- **<rule>**

## Counterparts

<related skills / files / tools the procedure leans on. Both within this plugin and across plugins.>

- `<plugin>:<skill>` — <how it relates>
```

### 3. Decide where it goes

Ask the user:

> Which plugin should this skill live in?
>
> - **`rudder@danielrosehill`** — if the procedure is about session UX, planning, or Claude Code itself
> - **<domain plugin>** — if the procedure is domain-specific (e.g., transcription work → `transcription-pipeline`, op-vault work → `op-vault`, etc.)
> - **In the project repo** at `<repo>/.claude/skills/<name>/SKILL.md` — if the procedure is specific to one repo and shouldn't be globally available

Suggest a default based on the procedure's domain, but **don't auto-pick**. The user often has a preference about scope.

### 4. Show the draft

Print the full draft SKILL.md to chat. Don't write it yet — let the user review.

> Draft of `<name>` SKILL.md (target: `<plugin>` or `<repo path>`):
>
> ```markdown
> [full draft]
> ```
>
> Ready to write? (yes / edit / wrong target / cancel)

### 5. Write and (optionally) push

If approved:

- **For a plugin target:**
  1. Create `<plugin-source-repo>/skills/<name>/SKILL.md`
  2. Bump plugin.json version (patch-bump unless user says otherwise)
  3. Commit with message: `Add <name> skill (extracted from session)`
  4. Push
  5. Update marketplace.json version if applicable
  6. Refresh marketplace cache and update the plugin

From danielrosehill/Claude-Rudder, MIT.

More from danielrosehill/Claude-Rudder