Skill Extract

---
name: skill-extract
description: "Extract reusable knowledge from the current session into a persistent skill.\nUse when you discover something non-obvious, create a workaround, or develop\na multi-step workflow that future sessions would benefit from."
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Bash(uv run python*)
  - AskUserQuestion
skill-dependencies: [proofread]
---

# 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`](../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:

| Recommendation | Criteria | Action |
|----------------|----------|--------|
| **PROCEED** | <20% overlap, genuinely new | Continue to Phase 3 |
| **EXTEND** | 50%+ overlap with one existing | Modify existing skill instead — stop here |
| **COMPOSE** | Multiple artifacts cover 80%+ | Create wrapper or document workflow — stop here |
| **ITERATE** | 20-50% overlap, needs refinement | Ask the user to clarify differentiation, then re-evaluate |
| **BLOCK** | Would create duplication | Do not create — stop here |

4. Present the skill-preflight analysis to the user and get explicit approval before proceeding
5. **Read [`skills/shared/skill-design-patterns.md`](../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

```yaml
---
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:

```markdown
# {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:

```markdown
# {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?

### Writing Rules

- **Imperative form.** "Parse the input" not "You should parse the input."
- **Be specific about what NOT to do.** Anti-pattern lists are highly effective.
- **Include concrete examples.** Show expected input/output pairs.
- **Keep SKILL.md under 300 lines.** Move detail to `references/`.
- **Every instruction must be actionable.** No throat-clearing.
- **Use tables for structured data.** Faster to parse than prose.

### Naming Conventions

- **Directory and name:** `kebab-case`, descriptive, 2-4 words
- **Avoid generic names:** `fix-bug` is bad; `fix-overleaf-sync-conflict` is good
- **Match the trigger:** If the natural trigger is "compile my slides", the name should relate to slide compilation

### Allowed Tools

Follow principle of least privilege:

| Skill type | Tools |
|-----------|-------|
| Report-only | `Read`, `Glob`, `Grep` |
| File-creating | + `Write`, `Edit` |
| Shell-needing | + specific `Bash(command*)` patterns |
| Interactive | + `the available structured-question mechanism` |
| Delegating | + `Task` |

## Phase 5: Validate

Run the validation script on the new skill:

```bash
uv run python skills/skill-extract/scripts/validate_skill.py skills/{name}
```

Fix all errors. Address warnings to improve quality. Use `--strict` to promote warnings to errors.

The validator checks: frontmatter validity, name format and directory match, description quality, body length, broken links, referenced directories, and placeholder text.

## Phase 6: Deploy and Confirm

1. Add an explicit client/capability row to
   `config/ai-skill-contracts.yaml`; never rely on a silent `both` default.
2. Add the new asset to `config/public-ai-contracts.yaml` as
   `distribution: exclude`. Public inclusion is a separate, user-owned
   whitelist decision: creating, approving, committing, syncing, or deploying
   the skill is not approval to publish it. Change it to `include` only after
   the user explicitly approves that named skill for the public distribution.
3. Update `docs/components/skills.md`, including the overview, full catalogue,
   and category subtotal, then run the inventory checker.
4. Render, validate, and deploy from the canonical control plane:
   ```bash
   uv run python scripts/ai_skill_contracts.py check
   uv run python scripts/public_framework.py check
   uv run python scripts/ai-infra-sync.py render
   uv run python scripts/ai-infra-sync.py deploy --target all --if-changed
   uv run python scripts/ai-infra-sync.py doctor --target all
   ```
5. Check that each declared client target contains the deployed `SKILL.md`.
6. Tell the user which clients received the skill and that public distribution
   remains excluded unless separately approved.

## What This Skill Does NOT Do

- **Does not replace `[LEARN]` tags** — one-liner corrections still go in MEMORY.md via the `learn-tags` rule; `skill-extract` is for multi-step procedures, not one-liners
- **Does not create agents** — agents need separate context and persistent memory
- **Does not modify existing skills** — if an existing skill needs updating, do that directly