Skip to main content

Guide

Adding Skills to Your Agent

Create custom slash commands and install community skills to extend what Claude Code can do.

By The Codegen Team · Updated June 2026

Key insight
Claude Code skills are SKILL.md files that add slash commands and on-demand workflows. Place a SKILL.md file in .claude/skills/your-command/ and Claude creates a /your-command you can invoke. Skills load only when needed, keeping your context budget free for actual work.
Key takeaways
  • Skills are markdown files with YAML frontmatter stored in .claude/skills/. The directory name becomes the slash command.
  • Write the primary use case first in the description. Claude truncates long descriptions when many skills compete for character budget.
  • Project skills (.claude/skills/) commit to your repo and share with your team. Personal skills (~/.claude/skills/) follow you across projects.
  • Use /doctor to diagnose skills that are not appearing. Character budget limits can truncate descriptions when many skills are installed.

What Are Skills and Why Use Them?

A skill is a markdown file that teaches Claude a specific workflow. Unlike CLAUDE.md, which loads into every session, skills load on demand. A deployment skill only costs context when you trigger a deployment. A code review skill only activates when Claude detects review-related work.

Each skill creates a slash command. A file at .claude/skills/deploy/SKILL.md becomes /deploy. Type it in your session and Claude reads the skill’s instructions, then follows them. You can also set skills to activate automatically based on context, so Claude applies them without being asked.

Claude Code ships with a few built-in skills like /code-review and /simplify. The real value comes from custom skills tailored to your project and workflow.

How to Create Your First Skill

Create a directory under .claude/skills/ in your project. The directory name becomes your slash command. Inside it, create a file named SKILL.md.

# Create the skill directory
mkdir -p .claude/skills/summarize-changes

# Create the skill file
touch .claude/skills/summarize-changes/SKILL.md

Open the file and add YAML frontmatter at the top, followed by your instructions in markdown. Here is a complete skill that summarizes uncommitted changes and flags anything risky:

---
description: Summarizes uncommitted changes and flags risks.
  Use when the user asks what changed or wants a commit message.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes in two or three bullet points.
List any risks: missing error handling, hardcoded values,
or tests that need updating.
If the diff is empty, say there are no uncommitted changes.

The description field is the most important line. Claude reads all skill descriptions at session start to know what is available, and uses them to decide when to load a skill automatically. Front-load the key use case in the first sentence because descriptions get truncated past 250 characters if you have many skills installed.

The !`git diff HEAD` line is dynamic context injection. Claude Code runs the command and replaces the line with its output before Claude sees the skill content. This keeps the instructions anchored to your actual working state.

How to Install a Community Skill

You do not have to write every skill from scratch. The community has built hundreds of reusable skills available on GitHub and through marketplaces like Agensi.

Installing a community skill means copying a directory into your skills folder. For a project-scoped skill:

# Clone or download the skill
git clone https://github.com/example/deploy-skill.git

# Copy into your project's skills directory
cp -r deploy-skill/.claude/skills/deploy .claude/skills/deploy

For a personal skill that works across all your projects, use the global directory:

# Personal skills go in ~/.claude/skills/
mkdir -p ~/.claude/skills/deploy
cp deploy-skill/SKILL.md ~/.claude/skills/deploy/SKILL.md

Project-scoped skills in .claude/skills/ are great for team conventions because they commit to your repo. Personal skills in ~/.claude/skills/ travel with you across projects. Both create the same slash command interface.

How to Verify a Skill Is Working

After creating or installing a skill, verify Claude sees it. Type / in your session and start typing the skill name. Claude Code’s autocomplete should show it in the list.

# Type / and filter
/summarize

# Claude should show:
# /summarize-changes - Summarizes uncommitted changes and flags risks.

If the skill does not appear, check two things. First, confirm the file is named exactly SKILL.md (case-sensitive) inside a directory under .claude/skills/. Second, run /doctor to see if skill descriptions are being truncated or dropped due to the character budget.

To test the skill itself, invoke it and check whether Claude follows the instructions. If it ignores part of the skill, the instructions may be too long or too vague. The same conciseness principles from CLAUDE.md apply. State what to do rather than narrating how or why. Keep the body focused. Once a skill loads, its content stays in context across turns as a recurring cost.

The next lesson covers MCP servers, which connect Claude to external tools and services rather than adding instructions.

Skills, agents, and rules referenced in this guide.

  • Skill Code Review Skill — Automated diff analysis that catches bugs, security issues, and code quality problems before merging

What's next

Keep building on what you just learned.

Browse skills for Claude Code Add power to every session Build an agent Assemble skills into a workflow Read more guides Go deeper on Claude Code

Frequently Asked Questions

Build faster with AI-powered agents

See how Codegen automates the full development workflow — from ticket to pull request.

Get Started →