update-skills

Update Skills & Instructions

When a major repository learning is discovered — a recurring pattern, a non-obvious pitfall, a crucial architectural constraint, or domain knowledge that would save future sessions significant time — capture it as a skill or instruction so it persists across sessions.

When to Use

• The user explicitly says "learn!" or asks to capture a learning
• You discover a significant pattern or constraint that cost meaningful debugging time
• You identify reusable domain knowledge that isn't documented anywhere in the repo
• A correction from the user reveals a general principle worth preserving

Decision: Skill vs Instruction vs Learning

Add a learning to an existing instruction when:

• The insight is small (1-4 sentences) and fits naturally into an existing instruction file
• It refines or extends an existing guideline
• Follow the pattern in .github/instructions/learnings.instructions.md

Create or update a skill (.github/skills/{name}/SKILL.md or .agents/skills/{name}/SKILL.md) when:

• The knowledge is substantial (multi-step procedure, detailed guidelines, or rich examples)
• It covers a distinct domain area (e.g., "how to debug X", "patterns for Y")
• Future sessions should be able to invoke it by name

Create or update an instruction (.github/instructions/{name}.instructions.md) when:

• The rule should apply automatically based on file patterns (applyTo) or globally
• It's a coding convention, architectural constraint, or process rule
• It doesn't need to be invoked on demand

Procedure

1. Identify the Learning

Reflect on what went wrong or what was discovered:

• What was the problem or unexpected behavior?
• Why was it a problem? (root cause, not symptoms)
• How was it fixed or what's the correct approach?
• Can it be generalized beyond this specific instance?

2. Check for Existing Files