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:

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.

1. Choose the smallest durable target using the Decision table.
2. 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.

1. 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.

1. 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.

1. 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.