Claude Code Skills and Custom Commands: Extend Claude's Capabilities

Key Takeaways#

• Skills load on demand — their body is injected into context only when invoked, so long reference material costs nothing until needed. CLAUDE.md is always loaded; skills are not.
• Use CLAUDE.md for facts, skills for procedures, commands for shortcuts. Each tool serves a distinct purpose. Pick the right one to keep your context window lean.
• Skill priority follows a clear hierarchy — Enterprise > Personal > Project > Plugin. Name conflicts resolve in that order.
• Custom slash commands are simple prompt shortcuts, not complex workflows. If you need templates, scripts, or multi-step logic, write a skill instead.
• Share skills across a team by committing .claude/skills/ to git or deploying through enterprise managed settings.

Skills vs CLAUDE.md vs Commands#

Claude Code gives you three mechanisms for extending behavior. Using the wrong one wastes context or creates maintenance headaches. Here's how to decide:

The critical distinction: skill body loads only when used. A 2,000-line API reference packaged as a skill costs zero tokens until someone invokes it. That same content in CLAUDE.md eats context every single session. Put facts in CLAUDE.md. Put everything else in skills.

Commands are the lightest mechanism — a single markdown file with a prompt template. They're ideal for shortcuts like /review this PR or /run lint. If your command needs templates, scripts, or multi-step instructions, promote it to a skill.

Skill Directory Structure#

A skill is a directory containing at minimum a SKILL.md file. You can add supporting files to keep the skill organized:

my-skill/
├── SKILL.md          # Required — frontmatter + instructions
├── template.md       # Output template for structured generation
├── examples/         # Example inputs/outputs Claude can reference
└── scripts/          # Shell scripts the skill can execute

• SKILL.md — The entry point. YAML frontmatter defines metadata; the body contains instructions Claude follows when the skill is invoked.
• template.md — A structured output template. Reference it from SKILL.md so Claude fills in the blanks rather than free-forming the output.
• examples/ — Concrete examples of the skill in action. Claude uses these to calibrate its behavior.
• scripts/ — Executable scripts the skill can run via allowed tools. Keep them focused and idempotent.

Skill Locations & Priority#

Skills live in four locations. When multiple skills share the same name, Claude resolves the conflict using this priority order:

1. Enterprise (managed settings) — Deployed organization-wide by admins. Highest priority.
2. Personal (~/.claude/skills/) — Your individual skills, available across all projects.
3. Project (.claude/skills/) — Checked into the repo, shared with the team.
4. Plugin — Installed via Claude Code plugins. Namespaced as plugin-name:skill-name.

If an enterprise skill and a project skill both define /deploy, the enterprise version wins. Plugin skills use their namespace to avoid collisions — invoke them as my-plugin:deploy rather than just deploy.

Live change detection: Adding, editing, or removing a skill takes effect within the current session. No restart required. Drop a new skill directory into .claude/skills/ and it's immediately available.

Frontmatter Reference#

SKILL.md frontmatter configures how and when the skill activates. Here are the key fields:

---
name: deploy                     # Skill name (used as /name)
description: Deploy to staging   # Short description for skill listing
when_to_use: Run when deploying  # When Claude should auto-suggest this skill
arguments:                       # Named arguments the skill accepts
  - name: environment
    description: Target environment
    required: true
disable-model-invocation: false   # If true, skill runs without an LLM call
user-invocable: true              # If false, only Claude can trigger it
allowed-tools:                    # Tools the skill is permitted to use
  - Bash
  - Read
model: claude-sonnet-4-20250514   # Override the model for this skill
effort: high                      # Reasoning effort: low, medium, high
context:                          # Additional files to inject into context
  - ./template.md
  - ./examples/
agent: true                        # Run as a sub-agent
hooks:                             # Lifecycle hooks
  - event: pre-invocation
    command: ./scripts/pre-deploy.sh
paths:                             # File patterns that trigger auto-suggestion
  - "deploy/**"
---

Important: The combined description + when_to_use text is truncated at 1,536 characters. Keep both concise. If you need to include lengthy context, put it in the SKILL.md body or reference files via the context field.

Bundled Skills#

Claude Code ships with several built-in skills you can use immediately:

These bundled skills follow the same loading behavior as custom skills — their instructions are only injected when invoked.

Creating a Custom Skill#

Let's build a deploy skill from scratch.

Step 1: Create the skill directory

mkdir -p .claude/skills/deploy

Step 2: Write SKILL.md with frontmatter and instructions

---
name: deploy
description: Deploy the project to a target environment
when_to_use: Use when the user asks to deploy, push to staging/production, or ship changes
arguments:
  - name: environment
    description: Target environment (staging, production)
    required: true
allowed-tools:
  - Bash
  - Read
paths:
  - "package.json"
  - "Dockerfile"
---

## Deploy Workflow

1. Read the current version from package.json
2. Run the test suite — abort if any test fails
3. Build the [Docker](/organizations/docker) image: `docker build -t app:${version} .`
4. Push to the registry: `docker push registry.example.com/app:${version}`
5. Update the deployment manifest for the target environment
6. Apply: `kubectl apply -f k8s/${environment}/deployment.yaml`
7. Verify: `kubectl rollout status deployment/app -n ${environment}`

Reference ./template.md for the deployment summary format.

Step 3: Add a template for structured output

Create .claude/skills/deploy/template.md:

# Deployment Summary

- **Version:** {version}
- **Environment:** {environment}
- **Image:** {image_url}
- **Status:** {status}
- **Timestamp:** {timestamp}

That's it. Invoke it with /deploy staging in your Claude Code session. The skill loads its instructions, reads the template, and executes the workflow step by step.

Custom Slash Commands#

Commands are the simplest extension point. A command is a single markdown file in .claude/commands/ that creates a slash shortcut:

mkdir -p .claude/commands

Write .claude/commands/deploy.md:

Deploy the current project to $ARGUMENTS. Run tests first, build, then push.

This creates the /deploy command. The $ARGUMENTS variable captures whatever the user types after the command name.

Skills merged with commands. If a skill and a command share the same name, the skill takes precedence. This lets you start with a simple command and graduate to a full skill without changing the invocation.

Keep commands simple. A command should be a short prompt template — one or two sentences. If you're writing multi-step instructions, adding templates, or referencing scripts, it belongs in a skill. The anti-pattern is a long list of complex custom commands that should have been skills. Commands are for shortcuts, not procedures.

Sharing Skills Across Teams#

Skills are designed to be shared. Two approaches:

1. Commit to git. Check .claude/skills/ into your repository. Every team member who clones the repo gets the skills immediately. This is the simplest method for most teams.

git add .claude/skills/deploy/
git commit -m "Add deploy skill"

2. Enterprise deployment. For organization-wide skills that shouldn't live in any single repo, use enterprise managed settings. Enterprise skills have the highest priority and override project-level skills with the same name. This is ideal for company-wide workflows like compliance checks, standardized deployment pipelines, or security review procedures.

Both approaches support live change detection — updates propagate without restarting sessions.

Best Practices#

• Start with CLAUDE.md, then extract. Put conventions in CLAUDE.md first. Once a section grows beyond a few paragraphs and isn't needed every session, extract it into a skill.
• One skill, one job. A skill should do one thing well. If you're tempted to put "deploy to staging" and "deploy to production" in separate skills, use arguments instead.
• Reference, don't duplicate. Use the context field to pull in templates and examples rather than embedding them in SKILL.md. This keeps the frontmatter body short and the skill maintainable.
• Name with verbs. /deploy, /debug, /review are clear. /deployment-stuff is not.
• Test your skills. Invoke them in a session and verify the output matches your expectations. Edit SKILL.md and re-invoke — the change takes effect immediately.