update-skills

name update-skills description Create or update repository skills and instructions when major learnings are discovered during a session. Use when the user says "learn!", when a significant pattern or pitfall is identified, or when reusable domain knowledge should be captured for future sessions. 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