Skill Extractor

Skill Extractor

Extracts reusable knowledge from work sessions and saves it as a Claude Code skill.

When to Use

• Just solved a non-obvious problem through investigation
• Discovered a workaround that required trial-and-error
• Found a debugging technique that would help in similar situations
• Learned a project-specific pattern worth preserving
• Fixed an error where the root cause wasn't immediately apparent

When NOT to Use

• Simple documentation lookups (just bookmark the docs)
• Trivial fixes (typos, obvious errors)
• One-off project-specific configurations
• Knowledge that's already well-documented elsewhere
• Unverified solutions (wait until it actually works)

Finding Extraction Candidates

Use these prompts to identify knowledge worth extracting:

• "What did I just learn that wasn't obvious before starting?"
• "If I faced this exact problem again, what would I wish I knew?"
• "What error message or symptom led me here, and what was the actual cause?"
• "Is this pattern specific to this project, or would it help in similar projects?"
• "What would I tell a colleague who hits this same issue?"

If you can't answer at least two of these with something non-trivial, it's probably not worth extracting.

Command

/skill-extractor [--project] [context hint]

• Default: saves to ~/.claude/skills/[name]/SKILL.md
• --project: saves to .claude/skills/[name]/SKILL.md
• Context hint helps focus extraction (e.g., /skill-extractor the cyclic data DoS fix)

Extraction Process

Step 0: Check for Existing Skills

Before creating a new skill, search for existing ones that might cover the same ground:

# Check user skills
ls ~/.claude/skills/

# Check project skills
ls .claude/skills/

# Search by keyword
grep -r "keyword" ~/.claude/skills/ .claude/skills/ 2>/dev/null

If a related skill exists, consider updating it instead of creating a new one. See skill-lifecycle.md for guidance on when to update vs create.

Step 1: Identify the Learning

If $ARGUMENTS contains a context hint (e.g., "the cyclic data DoS fix"), use it to focus the extraction on that specific topic.

Analyze the conversation to identify:

• What problem was solved?
• What made the solution non-obvious?
• What would someone need to know to solve this faster next time?
• What are the exact trigger conditions (error messages, symptoms)?

Present a brief summary to the user:

I identified this potential skill:

**Problem:** [Brief description]
**Key insight:** [What made it non-obvious]
**Triggers:** [Error messages or symptoms]

Step 2: Quality Assessment

Evaluate the candidate skill against these criteria:

Present assessment to user and ask: "Proceed with extraction? [yes/no]"

The user decides whether to proceed regardless of how many criteria pass. Respect their judgment - if they say yes, extract; if no, skip.

Step 3: Gather Details

Ask the user: 1. Skill name - Suggest a kebab-case name based on context, let them override 2. Scope - User-level (default) or project-level (--project)

Step 4: Optional Research

If the topic involves a specific library or framework:

• Use web search to find current best practices
• Use Context7 MCP (if available) for official documentation
• Include relevant sources in the References section

Skip research for:

• Project-specific internal patterns
• Generic programming concepts
• Time-sensitive extractions

Step 5: Generate the Skill

Use the template from skill-template.md.

Quality standards: Follow quality-guide.md to ensure the skill provides lasting value. Key points:

• Behavioral guidance over reference dumps
• Explain WHY, not just WHAT
• Specific triggers that compete well against other skills

Step 6: Validate Before Saving

Run through the validation checklist in skill-template.md. If validation fails, fix the issues before saving.

Step 7: Save the Skill

Create the directory and save:

• User-level: ~/.claude/skills/[name]/SKILL.md
• Project-level: .claude/skills/[name]/SKILL.md

Report success:

Skill saved to: [path]

The skill will be available in future sessions when the context matches:
"[first line of description]"

Memory Consolidation

When extracting, consider how the new knowledge relates to existing skills:

Combine or separate?

• Combine if the new knowledge is a variation or edge case of an existing skill
• Separate if it has distinct trigger conditions or solves a fundamentally different problem
• When in doubt, start separate - you can always merge later

Update vs create:

• Update an existing skill when you've discovered additional edge cases, better solutions, or corrections
• Create a new skill when the knowledge has different trigger conditions, even if the domain is related

Cross-referencing:

• If skills are related but separate, add a "See also" section linking them
• Example: A skill for "debugging connection pool exhaustion" might link to "serverless cold start optimization"

Skill Lifecycle

Skills aren't permanent. See skill-lifecycle.md for guidance on:

• Updating skills with new discoveries
• Deprecating skills when tools or patterns change
• Archiving skills that are no longer relevant

Rationalizations to Reject

If you catch yourself thinking any of these, do NOT extract:

• "This might be useful someday" - Only extract verified, reusable knowledge
• "Let me just save everything" - Quality over quantity
• "The user didn't confirm but it seems valuable" - Always get explicit confirmation
• "I'll skip the 'When NOT to Use' section" - It's mandatory for good skills
• "The description can be vague" - Specific triggers are essential for discovery

Example Extraction

Scenario: User discovered that an AST visitor crashes with RecursionError when analyzing serialized files containing cyclic references (e.g., a list that contains itself).

Identified learning:

• Cyclic data structures create cyclic ASTs
• Visitor pattern without cycle tracking causes infinite recursion
• Need to track visited nodes or enforce depth limits

Generated skill name: cyclic-ast-visitor-hardening

Key sections:

• When to Use: "RecursionError in AST visitor", "analyzing untrusted serialized input"
• When NOT to Use: "Recursion from deeply nested (but acyclic) structures"
• Problem: Visitor doesn't track visited nodes, enters infinite loop on cycles
• Solution: Add visited: set parameter, check before recursing
• Verification: Cyclic test case completes without RecursionError

Skill Quality Guide

Standards for generating high-quality skills that provide lasting value.

Before Generating

Required: Use the claude-code-guide subagent to review Anthropic's skill best practices documentation before generating. This ensures the skill follows current conventions for:

• Frontmatter structure
• Naming conventions
• Content organization
• Trigger descriptions

Value-Add Principle

Skills should provide guidance Claude doesn't already have.

DO:

• Behavioral guidance - When and how to apply knowledge
• Explain WHY - Trade-offs, decision criteria, judgment calls
• Anti-patterns WITH explanations - Why something is wrong, not just that it's wrong

DON'T:

• Reference dumps - Don't paste entire specs or docs
• Step-only instructions - "Do X, then Y" without explaining when or why
• Vague guidance - "Be careful with X" without specifics

Good example: A DWARF debugging skill doesn't include the full DWARF spec. It teaches how to use dwarfdump, readelf, and pyelftools to look up what's needed, plus judgment about when each tool is appropriate.

Description Triggers

Your skill competes with 100+ others for activation. The description determines when Claude uses it.

Anti-Pattern Examples

Bad: Reference Dump

## Solution
Here is the complete API documentation for the library...
[500 lines of copied docs]

Why it's bad: Claude can already look this up. No added value.

Bad: Steps Without Context

## Solution
1. Run `uv add httpx`
2. Add `import httpx`
3. Call `httpx.get(url)`

Why it's bad: No explanation of when this applies or what problems it solves.

Bad: Vague Triggers

description: "Helps with database issues"

Why it's bad: Will either never trigger or trigger too often.

Good: Behavioral Guidance

## When to Use
- `ECONNREFUSED` on port 5432 after mass test runs
- "too many connections" in CI but not locally
- Connection works initially, fails after ~100 requests

## Problem
Connection pool exhaustion in serverless environments where each invocation
creates new connections but the runtime persists.

## Solution
### Why this happens
Serverless functions reuse the execution context but not the connection state...

### Step 1: Diagnose
Check current connections: `SELECT count(*) FROM pg_stat_activity;`
If > max_connections, this is the issue.

### Step 2: Fix
[Specific fix with explanation of WHY it works]

Scope Boundaries

Match prescriptiveness to task risk:

Skill Lifecycle

Skills evolve over time. This guide covers updating, deprecating, and archiving skills.

Updating Existing Skills

When to Update

Update an existing skill when:

• You've discovered additional edge cases or exceptions
• A better solution exists than what's documented
• The original solution had errors or gaps
• New versions of tools or libraries change the approach
• You've found clearer ways to explain the concept

How to Update

1. Add, don't replace (unless the original was wrong)

• Add new edge cases to a "Variations" or "Edge Cases" section
• Keep the original solution if it still works for the common case

2. Bump the version in frontmatter if using versioning

   version: 1.1.0  # was 1.0.0

3. Add a changelog at the bottom for significant updates

   ## Changelog
   - 2025-01-15: Added workaround for v2.0 API changes
   - 2024-06-01: Initial extraction

4. Update triggers in the description if new symptoms were discovered

What NOT to Do When Updating

• Don't remove working solutions just because you found a "better" one - document both
• Don't change the skill name unless the scope has fundamentally changed
• Don't update based on a single new case - wait for a pattern

Deprecating Skills

When to Deprecate

Deprecate a skill when:

• The underlying tool, library, or API has changed significantly
• The problem the skill solved no longer exists (e.g., a bug was fixed upstream)
• A better skill now covers the same ground
• The approach is now considered bad practice

How to Deprecate

1. Add a deprecation notice at the top of the skill:

   > **DEPRECATED (2025-01-15):** This skill applies to v1.x only.
   > For v2.x, see [new-skill-name](path/to/new-skill).

2. Update the description to include "DEPRECATED":

   description: |
     DEPRECATED - See new-skill-name instead. [Original description...]

3. Keep the skill for users who might still be on older versions

• Don't delete immediately
• Move to deprecation after 6+ months if the old version is truly dead

Deprecation vs Deletion

• Deprecate when some users might still need it
• Delete only when the skill is actively harmful or completely irrelevant

Archiving Skills

When to Archive

Archive a skill when:

• It's been deprecated for 6+ months with no usage
• The technology it covers is completely obsolete
• It was project-specific and the project is dead

How to Archive

1. Move to an archived/ directory:

   ~/.claude/skills/archived/old-skill-name/SKILL.md

2. Or delete if archiving isn't worth the disk space

3. Document why in a brief note if keeping:

   > Archived 2025-01-15: Python 2 is EOL, this is no longer relevant.

Lifecycle Summary

Review Cadence

Consider reviewing skills periodically:

• After major tool updates - Check if skills for that tool still apply
• When a skill triggers but doesn't help - It may need updating or deprecation
• Every 6-12 months - Quick scan for obviously outdated content

Skill Template

Copy this template when generating a new skill.

---
name: [kebab-case-name]
description: >-
  [Third-person description with specific triggers. Example: "Detects infinite
  recursion vulnerabilities in AST visitors from cyclic data structures. Use
  when: (1) RecursionError during tree traversal, (2) analyzing untrusted
  serialized data, (3) visitor pattern without cycle detection."]
author: Claude Code
version: 1.0.0
date: [YYYY-MM-DD]
---

# [Human Readable Title]

## When to Use

- [Specific scenario 1]
- [Specific scenario 2]
- [Exact error message if applicable]

## When NOT to Use

- [Scenario where this doesn't apply]
- [Better alternative for related but different problem]

## Problem

[Clear description of what this solves and why it's non-obvious]

## Solution

### Step 1: [Action]

[Instructions with code examples]

### Step 2: [Action]

[Continue with clear steps]

## Verification

1. [How to confirm it worked]
2. [Expected outcome]

## References

- [Link to official docs if researched]
- [Web source if consulted]

Validation Checklist

Before saving, verify:

• [ ] Name is kebab-case, max 64 characters
• [ ] Description is third-person ("Fixes X" not "I help with X")
• [ ] Description includes specific trigger conditions
• [ ] "When to Use" section is present and specific
• [ ] "When NOT to Use" section is present
• [ ] Solution has concrete steps
• [ ] No hardcoded paths (/Users/..., /home/...)
• [ ] Under 500 lines total