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

Before creating new files, search for existing skills and instructions that might be the right home:

# Check existing skills
ls .github/skills/ .agents/skills/ 2>/dev/null

# Check existing instructions
ls .github/instructions/ 2>/dev/null

# Search for related content
grep -r "related-keyword" .github/skills/ .github/instructions/ .agents/skills/

3a. Add to Existing File

If an appropriate file exists, add the learning to its ## Learnings section (create the section if it doesn't exist). Each learning should be 1-4 sentences.

3b. Create a New Skill

If the knowledge warrants a standalone skill:

Choose the location:
- .github/skills/{name}/SKILL.md for project-level skills (committed to repo)
- .agents/skills/{name}/SKILL.md for agent-specific skills
Create the directory and SKILL.md with frontmatter:

---
name: {skill-name}
description: {One-line description of when and why to use this skill.}
---

# {Skill Title}

{Body with guidelines, procedures, examples, and learnings.}

The name field must match the parent folder name exactly.
Include concrete examples — skills with examples are far more useful than abstract rules.

3c. Create a New Instruction

If the knowledge should apply automatically:

---
description: {When these instructions should be loaded}
applyTo: '{glob pattern}' # optional — auto-load when matching files are attached
---

{Content of the instruction.}

4. Quality Checks

Before saving:

Is the learning general enough to help future sessions, not just this one?
Is it specific enough to be actionable, not just a vague principle?
Does it include a concrete example of right vs wrong?
Does it avoid duplicating knowledge already captured elsewhere?
Is the description clear enough that the agent will know when to invoke/apply it?

5. Inform the User

After creating or updating the file:

Summarize what was captured and where
Explain why this location was chosen
Note if any existing content was updated vs new content created

update-skills