update-skills

<!-- Customize this skill and select save to override its behavior. Delete that copy to restore the built-in behavior. --> # 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: 1. Choose the location: - `.github/skills/{name}/SKILL.md` for project-level skills (committed to repo) - `.agents/skills/{name}/SKILL.md` for agent-specific skills 2. Create the directory and SKILL.md with frontmatter: ```markdown --- name: {skill-name} description: {One-line description of when and why to use this skill.} --- # {Skill Title} {Body with guidelines, procedures, examples, and learnings.} ``` 3. The `name` field **must match** the parent folder name exactly. 4. Include concrete examples — skills with examples are far more useful than abstract rules. ### 3c. Create a New Instruction If the knowledge should apply automatically: ```markdown --- 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