update-skills

Write down what you learned the hard way this session so the next one does not have to rediscover it, and work out where it belongs — a page of its own, or a line added to notes that already exist.

WHEN TO USE

SCOPE

USE FOR

Turn a debugging discovery that cost real time into a skill future sessions can reuse.
Decide whether a new learning belongs in a skill, an instruction, or an existing file's notes.
Create a new skill file with the metadata header and structure this repository's skills require.
Add a short learning to an existing instruction file instead of creating a new one.

This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.

In this document (4)

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

No requirements beyond installing this skill were found.

Listed as free: Connected services may require an account or charge fees.
Installation: One command — usually under 2 minutes.

One of 31 skills in the microsoft/vscode package — works on its own.

Run this outside your AI tool, using Node.js 22.20.0 or newer. Skills CLI 1.7.2 skips skill selection; prompts cancel installation without an interactive terminal. If choosing Project when asked about installation scope, open your project's folder before running this.

Install checklist

Check selected tools if a picker appears; Claude Code may be unchecked under Additional agents. ↑/↓ moves, Space toggles selections, Enter confirms.
Without a tool picker, check Installing to: for your intended tool. Stop if it names a different tool.
If asked, choose Symlink (Recommended) for shared files or Copy to all agents for separate copies; review the summary before confirming installation.
Install the find-skills skill? defaults to Yes, adding another skill for all projects. Choose No if you don't want that extra installation.

Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.

npx skills add microsoft/vscode --skill "update-skills" --full-depth

After installing for Claude Code, open it in the installation project if you chose Project; Global makes the skill available across projects on this computer. Once Claude Code loads the skill, its description helps Claude decide when to use it.

If installation created a top-level skills folder that did not exist when your Claude Code session started, run /reload-skills in that session. Run it again after later changes in that folder.

What's inside

Files included with this skill.

View on GitHub

The repository is licensed under MIT — use, modification, and redistribution are allowed under that license’s terms.

View the repository’s license file on GitHub →

Update Skills & Instructions

When to Use

Decision: Skill vs Instruction vs Learning

Procedure

1. Identify the Learning

2. Check for Existing Files

3a. Add to Existing File

3b. Create a New Skill

3c. Create a New Instruction

4. Quality Checks

5. Inform the User

No requirements beyond installing this skill were found.

What's inside

More skills

act-on-feedback

agent-customization

author-contributions

chronicle

code-review

commit