hard-won-skill-extractor

name	hard-won-skill-extractor
description	Use when a tricky bug, non-obvious workaround, hidden gotcha, or undocumented behavior took real debugging effort to discover and should be captured as a reusable learned skill.

Hard-Won Skill Extractor

This skill serves to document how to manually extract a useful learned skill into a reusable markdown file.

Core Principle

Reusable skills are not code snippets to copy-paste, but principles and decision-making heuristics that teach an agent HOW TO THINK about a class of problems.

The difference:

• BAD (mimicking): "When you see ConnectionResetError, add this try/except block"
• GOOD (reusable skill): "In async network code, any I/O operation can fail independently due to client/server lifecycle mismatches. The principle: wrap each I/O operation separately, because failure between operations is the common case, not the exception."

Quality Gate

Before extracting a skill manually, ALL three must be true:

• "Could someone Google this in 5 minutes?" → NO
• "Is this specific to THIS codebase?" → YES
• "Did this take real debugging effort to discover?" → YES

Recognition Signals

Extract ONLY after:

• Solving a tricky bug that required deep investigation
• Discovering a non-obvious workaround specific to this codebase
• Finding a hidden gotcha that wastes time when forgotten
• Uncovering undocumented behavior that affects this project

What Makes a USEFUL Skill

1. Non-Googleable: Something you couldn't easily find via search
2. Context-Specific: References actual files, error messages, or patterns from THIS codebase
3. Actionable with Precision: Tells you exactly WHAT to do and WHERE
4. Hard-Won: Took significant debugging effort to discover

Anti-Patterns (DO NOT EXTRACT)

• Generic programming patterns (use documentation instead)
• Refactoring techniques (these are universal)
• Library usage examples (use library docs)
• Type definitions or boilerplate
• Anything a junior dev could Google in 5 minutes

Manual Extraction Workflow

Step 1: Gather Required Information

• Problem Statement: The SPECIFIC error, symptom, or confusion that occurred
• Solution: The EXACT fix, not general advice
• Triggers: Keywords that would appear when hitting this problem again
• Scope: Almost always Project-level unless it's a truly universal insight

Step 2: Quality Validation

Reject skills that are:

• Too generic
• Easily Googleable
• Vague solutions
• Poor triggers

Step 3: Save Location

• Project-level: .skills/<skill-name>.md - Default. Intended to be committed with the repo.

Step 4: Promote if reusable

If the extracted idea should become a maintained, shareable skill instead of a project-local note, switch to skill-authoring-guide and turn it into a proper skill folder with frontmatter, support files, and validation.

Required File Format

Every learned skill file MUST start with YAML frontmatter. Do not write plain markdown without frontmatter.

After the frontmatter, use a pure Markdown body with headings. Do not use XML-like tags such as <Purpose> or <Workflow> as default top-level structure; reserve XML-like delimiters for nested examples, quoted input, external documents, or machine-readable prompt payloads.

Minimum required frontmatter:

---
name: <skill-name>
description: <one-line description>
triggers:
  - <trigger-1>
  - <trigger-2>
---

Skill Body Template

---
name: <skill-name>
description: <one-line description>
triggers:
  - <trigger-1>
  - <trigger-2>
---

# [Skill Name]

## The Insight
What is the underlying PRINCIPLE you discovered? Not the code, but the mental model.

## Why This Matters
What goes wrong if you don't know this? What symptom led you here?

## Recognition Pattern
How do you know when this skill applies? What are the signs?

## The Approach
The decision-making heuristic, not just code. How should an agent THINK about this?

## Example (Optional)
If code helps, show it - but as illustration of the principle, not copy-paste material.

Verification

• All three quality-gate questions hold: not Googleable in 5 minutes, specific to this codebase, took real debugging effort
• The saved file starts with YAML frontmatter including name, description, and triggers
• The body teaches the principle and recognition pattern — not copy-paste code
• Anti-pattern content (generic patterns, library usage, boilerplate) was rejected, not extracted
• Truly reusable insights were promoted via skill-authoring-guide instead of staying project-local