learner

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