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:

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 — 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?

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:

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:

   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