Your First Skill

The skill that does not exist yet

Every developer eventually has a session where they ask Claude to summarize their uncommitted changes before writing a commit message. Then they ask again next session. And the session after that. This is the ideal first skill: simple, genuinely useful, and completely repetitive.

Building it takes three steps. Understanding where it lives takes one paragraph.

Where skills live

Skills can exist at four levels. The two you will use most often are personal (available across all your projects) and project (checked into this repository, available to the whole team):

Start with personal. Move to project when teammates need it too.

Creating the summarize-changes skill

Open a terminal and create the skill directory:

mkdir -p ~/.claude/skills/summarize-changes

Save this to ~/.claude/skills/summarize-changes/SKILL.md:

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

That is the complete skill. The description field tells Claude when to invoke it automatically. The !`git diff HEAD` line pulls in your live diff before Claude reads anything — more on that in the next lesson.

Testing the skill

Open a project in Claude Code, make a small edit to any file, then start a session. You have two ways to invoke the skill:

Direct invocation: Type /summarize-changes. Claude loads the skill immediately.

Natural language: Ask "what did I change?" or "can you summarize my diff?" Claude reads the description and loads the skill automatically when the request matches.

Claude Code watches skill directories for file changes. If you edit SKILL.md, the change takes effect in the current session without restarting. This makes iteration fast: edit, switch to Claude Code, try again.

The legacy commands path

If you have files in .claude/commands/ from before the skills system existed, they still work. A file at .claude/commands/deploy.md creates a /deploy command exactly as before. Skills add optional features on top — supporting directories, additional frontmatter fields, subagent execution — but you do not need to migrate existing commands. If a skill and a command share the same name, the skill takes precedence.

Bundled skills: what already ships with Claude Code

Before building a skill from scratch, check whether a bundled skill already does what you need. Claude Code ships eight built-in skills available in every session:

• /code-review — structured code review against best practices
• /debug — systematic debugging workflow
• /loop — autonomous iterative task mode
• /batch — parallel multi-task execution
• /claude-api — tasks that involve the Claude API itself
• /run — launches your app to verify a change works
• /verify — builds and runs the app to confirm a specific change
• /run-skill-generator — records how to build and launch your project

The /run, /verify, and /run-skill-generator trio is worth understanding as a unit. Claude Code can infer how to launch simple projects from a package.json or Makefile, but inference breaks down when your project needs a database, an env file, or a multi-step build. Run /run-skill-generator once: it gets your app running from scratch, captures what worked, and commits that recipe as a project skill at .claude/skills/run-<name>/. After that, both /run and /verify follow the recorded recipe instead of guessing.

You can override any bundled skill by creating a same-named skill in your project or personal directory. A .claude/skills/code-review/SKILL.md in your repo replaces /code-review for everyone working on that project. This is the standard way to enforce team-specific review standards without changing global behavior.

Skill content lifecycle

When you or Claude invoke a skill, its rendered content enters the conversation as a single message and stays there for the rest of the session. Claude Code does not re-read the skill file on later turns — the content is already in context.

When Claude Code summarizes a long session to free context space, it re-attaches the most recent invocation of each skill afterward, keeping up to 5,000 tokens of each. All re-attached skills share a combined budget of 25,000 tokens. If you have invoked many skills and a session gets summarized, some older skill content may be dropped entirely.

If a skill seems to stop influencing Claude's behavior partway through a long session, the most common cause is compaction. Re-invoke the skill with /skill-name to restore the full content.