Skill Extract

Learn: Session Knowledge Extraction

Extract reusable workflows, workarounds, and multi-step procedures discovered during a session into persistent skills. Complementary to the learn-tags rule — while [LEARN] tags record one-liner corrections in MEMORY.md, skill-extract creates full skill definitions in skills/.

When to Use

• You discovered a non-obvious multi-step procedure
• You built a workaround for a recurring problem
• You developed a workflow that future sessions would benefit from
• the user says "save this as a skill", "learn this", or "remember how to do this"

Phase 1: Evaluate

Before creating anything, answer these 4 self-assessment questions:

1. Non-obvious? Would a future session figure this out without help, or would it waste time rediscovering it?
2. Future benefit? Will this come up again across sessions or projects?
3. Repeatable? Is this a procedure that can be followed step-by-step, or was it a one-off?
4. Multi-step? Does it involve 2+ non-trivial steps that benefit from being documented together?

Decision rule: If at least 3 of 4 answers are "yes", proceed to Phase 2. Otherwise, suggest recording as a [LEARN] tag in MEMORY.md instead (simpler, lower overhead).

If borderline, ask the user:

"This seems useful but may not warrant a full skill. Should I create a skill or just add a [LEARN] tag to MEMORY.md?"

Phase 2: Creation Guard + Read Patterns

Run the skill-preflight analysis (see skills/skill-preflight/SKILL.md):

1. Identify the proposal (name, type, purpose, key functions, keywords)
2. Search existing skills and agents for overlap (skill-index scan + keyword grep)
3. Analyse overlap and generate a recommendation:

4. Present the skill-preflight analysis to the user and get explicit approval before proceeding
5. Read skills/shared/skill-design-patterns.md — choose the structural pattern that fits:
   • Workflow-based — multi-step with phases and review gates
   • Task-based — focused input/output with processing rules
   • Agent-delegation — multiple subagents, each handling one concern
   • Reference-based — augmenting with domain knowledge via references/

Phase 3: Design the Skill

Before writing, make three decisions:

1. Choose the structural pattern (from Phase 2). State it explicitly:

"This is a [workflow/task/agent-delegation/reference]-based skill."

2. Identify resources needed:

• Does the skill need scripts/ for deterministic operations?
• Does it need references/ for detailed specs, rubrics, or large examples?
• Does it need to delegate to subagents?

3. Draft the architecture — for non-trivial skills, sketch the flow:

Input → [Step A] → REVIEW GATE → [Step B] → Output

Phase 4: Build the Skill

Write skills/{name}/SKILL.md:

Frontmatter

---
name: {kebab-case-name}
description: "{What it does. Concrete task types. Use when...}"
allowed-tools:
  - {minimum set of tools needed}
---

Body Structure

The body varies by pattern, but always includes these elements:

# {Skill Name}: {Short Description}

## When to Use
[Activation conditions — natural language triggers and /command]

## {Main Workflow / Processing Rules / Delegation Protocol}
[The core of the skill — structured per the chosen pattern]

## {Anti-Patterns / Never Do These}
[What NOT to do — agents default to generic without constraints]

## Output Format
[What the output looks like]

## Verification
[How to confirm it worked]

Optional sections (add when relevant):

• ## Defaults — assumptions table to reduce friction
• ## Examples — concrete before/after or good/bad snippets
• ## Notes — edge cases, limitations

Solution Pattern (for debugging/workaround skills)

When the skill captures a fix, workaround, or debugging procedure, use this body structure:

# {Skill Name}: {Short Description}

## Problem
[Specific error message or symptom. Quote the exact text users would see.]

## Context / Triggers
[When this occurs — tool versions, file types, OS, configurations]

## Solution
[Step-by-step fix. Imperative form.]

## Verification
[How to confirm the fix worked]

## Example
[Concrete before/after or input/output]

## Notes
[Edge cases, alternative approaches, when this does NOT apply]

Description Optimization

The description: field in frontmatter is what triggers skill discovery. Write it to match how a user would describe their problem:

• Include specific error messages or symptoms — "Fix Package biblatex Error: File 'references.bib' not found"
• Include context markers — file types, tools, situations where this applies
• Include negative cases — "Not for general proofreading (use proofread instead)"
• Use natural trigger phrases — the exact words a user would type

Extraction Checklist

During skill creation, mentally verify each point before finalising:

1. Trigger coverage — would a user find this skill from 3 different phrasings of the same problem?
2. Self-contained — can the skill be followed without reading other files (except references/)?
3. Anti-patterns present — at least 2 "don't do this" entries to prevent common mistakes?
4. Verification step — does the skill tell you how to confirm it worked?
5. Scope bounded — is it clear what this skill does NOT do?