Learner

Convert real SDD usage into durable operating knowledge.

Use this workflow to decide whether a lesson belongs in:

• an existing skill,
• a new skill,
• .claude/memory/annotations.md,
• another Tier 2 memory file,
• or no durable artifact.

Source Principles

This workflow adopts the Agent Skills guidance that durable skills come from real expertise, project artifacts, execution traces, and repeated refinement. Skills should capture team-specific process and failure modes, not generic best practices or deterministic glue better handled by scripts, hooks, or MCP.

Extraction Gate

Create or modify a skill only when at least one signal is present:

• Agent made a wrong choice despite a correct prompt.
• Existing skill fired but failed its mission.
• Needed skill did not fire because description was weak or absent.
• A teammate/user wrote the same long prompt, plan, or checklist a second time.
• Session repeated a costly investigation, setup, verification, or handoff loop.
• User corrected a project convention, team preference, or non-obvious edge case.
• Internal process, internal system, or proprietary data pattern must be reused.

Do not create a skill for:

• General advice the model already knows.
• One-off code snippets.
• Secrets, credentials, or environment-specific auth hacks.
• Simple deterministic checks better implemented as hooks, scripts, tests, or MCP.
• Large copied docs without a clear load condition.

Decision

Classify the lesson before editing:

Lesson type	Target
Existing workflow missed a rule, edge case, or output shape	Update that skill body
Existing skill should have fired but did not	Tighten that skill description
Repeated team-specific process forms a coherent unit	Create or update a skill
Non-obvious caveat tied to a service/library/repo area	Use annotate memory
Broad preference or project operating rule	Update the right Tier 2 memory/doc
Deterministic repeated operation	Prefer tested script/hook/MCP; skill only orchestrates when needed

Prefer updating an existing skill over adding a new one when the lesson fits an existing coherent workflow.

Workflow

1. Gather evidence:
   • original prompt or task,
   • correction or failure mode,
   • first point where the agent went wrong,
   • skills that fired or failed to fire,
   • files, commands, traces, review comments, or user preferences involved.
2. Choose the smallest durable target using the Decision table.
3. Edit with progressive disclosure:
   • keep SKILL.md under 500 lines when practical,
   • keep only always-needed instructions in SKILL.md,
   • move long examples, schemas, or domain references into references/,
   • state exactly when to read each reference file.
4. Tune invocation:
   • put trigger phrases and scope in description,
   • add exclusions when false positives are likely,
   • avoid relying on body-only "when to use" text for activation.
5. Preserve SDD gates:
   • do not weaken using-sdd, permissions, hooks, or source-of-truth rules,
   • route spec, plan, code, review, and release changes through their owning skills.
6. Validate:
   • run powershell -ExecutionPolicy Bypass -File scripts\validate-skills.ps1,
   • run node scripts\validate-readme-sync.js if counts or README inventory changed,
   • run node scripts\harness-audit.js --compact for routing, hook, or harness changes.

Skill Edit Rules

• Add what the agent lacks; cut what generic model knowledge already covers.
• Prefer procedures over declarations.
• Use defaults, not broad menus of equal options.
• Make fragile operations prescriptive; leave flexible judgment where multiple approaches are valid.
• Add concrete gotchas where the agent is likely to make the wrong assumption.
• Keep bundled scripts deterministic and tested.
• Treat each skill like a function: one coherent responsibility, composable with other skills.

New Skill Template

Use this shape when a new SDD skill is justified:

---
name: short-action-name
type: workflow
description: "What this skill does. Use when <specific trigger phrases, task contexts, and boundaries>."
argument-hint: "[expected input]"
user-invocable: true
allowed-tools: Read, Glob, Grep
effort: 2
when_to_use: "One sentence matching the description scope for SDD docs and humans."
---

# Purpose

State the reusable team-specific capability.

## Workflow

1. Do the first required action.
2. Make the context-dependent decision.
3. Verify with a concrete check.

## Gotchas

- Add only non-obvious failure modes discovered from real use.

## Output

Specify the exact artifact or response shape when consistency matters.

Completion Output

Report:

• artifact changed or created,
• evidence source that justified it,
• validation commands and results,
• remaining skill debt or telemetry gap.