The Skill System

Skills are the building blocks of automation in Claude Code. Learn how to create reusable instruction files that turn repetitive tasks into one-command operations.

What Are Skills?

A skill is a reusable .md file that contains structured instructions for Claude Code. Think of it as a recipe: instead of explaining the same process every time, you write it once and invoke it by name. Skills live in your project's .claude/skills/ directory and are available to every session in that project.

Without skills, you might find yourself typing the same multi-paragraph prompt every time you want Claude to perform a specific task — researching a competitor, formatting a report, cleaning up a CSV. Skills eliminate that repetition entirely. You describe the process once in a markdown file, and from then on you invoke it with a single slash command.

The Skill File Format

Every skill file follows a consistent markdown structure. The filename becomes the command name, so research.md is invoked with /research. Here is the anatomy of a well-structured skill file:

# Skill: Research Company

## Description
Research a company and produce a structured brief.

## Inputs
- **company_name** (required): The name of the company to research
- **focus_area** (optional): Specific area to focus on (product, funding, team, etc.)

## Instructions
1. Search for the company's website and recent news
2. Identify key information:
   - What the company does (one-sentence summary)
   - Founding year and location
   - Funding history and current stage
   - Key team members
   - Recent news or product launches
3. If a focus_area is provided, go deeper on that topic
4. Compile findings into the output format below

## Output Format
### {company_name} — Company Brief
**Summary:** One-sentence description
**Founded:** Year, Location
**Funding:** Stage and total raised
**Team:** Key people and roles
**Recent Activity:** 2-3 bullet points
**Focus Area Deep Dive:** (if applicable)

## Constraints
- Use only publicly available information
- Flag anything that seems outdated (> 6 months)
- Keep the brief under 500 words

Breaking Down the Anatomy

• Skill name — The top-level heading identifies what the skill does. Keep it clear and action-oriented.
• Description — A one-liner that appears when you browse available skills. Helps you (and teammates) understand the skill at a glance.
• Inputs — Define what information the skill needs. Mark parameters as required or optional. This tells Claude what to ask for if you don't provide it upfront.
• Instructions — The step-by-step process Claude follows. Be specific. Numbered steps work better than vague directions.
• Output Format — Define what the result should look like. A template prevents Claude from choosing a different format each time.
• Constraints — Guardrails and rules. Word limits, source restrictions, tone guidelines, what to include or exclude.

Creating Your First Skill

Let's walk through creating a practical skill from scratch. We'll build a "summarize article" skill that takes a URL, reads the content, and produces a structured summary.

mkdir -p .claude/skills

# Skill: Summarize Article

## Description
Read a URL and produce a structured summary with key takeaways.

## Inputs
- **url** (required): The URL of the article to summarize
- **length** (optional): "brief" (3 bullets) or "detailed" (full summary). Default: "detailed"

## Instructions
1. Fetch and read the content at the provided URL
2. Identify the article's main thesis or argument
3. Extract the 3-5 most important points
4. Note any data, statistics, or quotes worth preserving
5. Identify the author and publication date if available

## Output Format
### Summary: {article_title}
**Source:** {url}
**Author:** {author} | **Date:** {date}

**Main Thesis:** One sentence capturing the core argument.

**Key Points:**
- Point 1
- Point 2
- Point 3

**Notable Data/Quotes:**
- Any standout statistics or direct quotes

**My Take:** One-sentence editorial note on relevance or quality.

## Constraints
- Do not editorialize beyond the "My Take" section
- Preserve the author's intent; do not misrepresent arguments
- If the URL is inaccessible, say so immediately rather than guessing

/summarize url=https://example.com/some-article

How to Invoke Skills

Once a skill file exists in .claude/skills/, you invoke it with a slash command that matches the filename. There are several ways to pass inputs:

Inline Invocation

Pass all parameters directly in your message:

/research company_name=Stripe focus_area=product

Conversational Invocation

Just invoke the skill name and provide context naturally. Claude will extract the parameters from your message:

/research
I'd like a brief on Notion, specifically their recent AI features and enterprise push.

Chaining Skills

You can ask Claude to run multiple skills in sequence. The output of one skill can feed into the next:

First, /research company_name=Acme Corp
Then, /draft-email using the research results to write an intro email.

Skill Parameters and Customization

Well-designed parameters make your skills flexible without making them complicated. Here are patterns that work well:

Required vs. Optional Parameters

Mark the minimum information needed as required. Everything else should be optional with sensible defaults. If a skill has more than 3 required parameters, it may be doing too much — consider splitting it into multiple skills.

## Inputs
- **topic** (required): The subject to write about
- **audience** (optional): Target reader. Default: "general business audience"
- **tone** (optional): Writing style. Default: "professional but approachable"
- **word_count** (optional): Target length. Default: 500

Enum-Style Parameters

When a parameter should be one of a few specific values, list the options explicitly. This prevents ambiguity and makes the skill more predictable:

## Inputs
- **format** (optional): Output format. One of:
  - "slack" — Short, emoji-friendly, conversational
  - "email" — Professional with greeting and sign-off
  - "document" — Formal with headers and sections
  Default: "document"

Conditional Instructions

You can include branching logic in your instructions. Claude follows these naturally:

## Instructions
1. Analyze the provided data file
2. If the file is a CSV:
   - Check for missing values and report the count per column
   - Identify duplicate rows
   - Validate data types per column
3. If the file is JSON:
   - Validate the schema
   - Check for null or empty fields
   - Report nesting depth
4. Regardless of format, produce the standardized report below

Example: Research Process to Reusable Skill

Let's walk through a real transformation. Suppose every week you research competitors for your team. Currently, the process looks something like this:

Before: The Manual Process

Every Monday, you open Claude Code and type something like:

Can you research what Competitor X has been up to this week? Check their
blog, social media, any press releases. I need to know about product
updates, new hires, pricing changes, and partnerships. Format it as
bullet points I can paste into our Slack channel. Keep it under 300 words.
Oh, and flag anything that's a direct threat to our product.

This works, but you re-type a variation of this prompt every single week. Sometimes you forget to ask about pricing. Sometimes the format varies. The output is inconsistent.

After: The Skill File

Here is the same process codified as a reusable skill at .claude/skills/competitive-intel.md:

# Skill: Competitive Intel

## Description
Weekly competitive intelligence brief for a specific competitor.

## Inputs
- **competitor** (required): Company name to research
- **our_product** (optional): Our product name, for threat analysis. Default: use CLAUDE.md context
- **period** (optional): Time window. Default: "past 7 days"

## Instructions
1. Search for recent activity from {competitor}:
   - Official blog posts and press releases
   - Social media announcements (LinkedIn, X/Twitter)
   - News coverage and media mentions
   - Job postings (signal for new initiatives)
2. Categorize findings into:
   - Product Updates (new features, launches, deprecations)
   - Business Moves (funding, partnerships, acquisitions)
   - Pricing/Packaging changes
   - Team Changes (key hires, departures)
3. For each finding, assess threat level:
   - 🔴 Direct threat to {our_product}
   - 🟡 Worth monitoring
   - 🟢 Not directly relevant
4. Summarize into the output format below

## Output Format
## {competitor} — Weekly Intel ({period})

**TL;DR:** One-sentence summary of the most important development.

### Product Updates
- Finding (threat level)

### Business Moves
- Finding (threat level)

### Pricing/Packaging
- Finding (threat level) or "No changes detected"

### Team Changes
- Finding or "No notable changes"

### Action Items
- Specific things our team should do in response

## Constraints
- Stay under 300 words
- Use Slack-friendly formatting (bullet points, bold, emoji)
- If no activity found in a category, say so explicitly
- Flag stale information (> 30 days old) even if within the search period

Now your Monday routine is a single command:

/competitive-intel competitor=Acme Corp

The output is consistent every week. Nothing gets missed. And if your team wants to adjust the format, you edit one file instead of remembering to phrase your prompt differently.

Best Practices

• Name skills as verbs. Use research.md, draft-email.md, clean-data.md — not email-stuff.md.
• Keep skills focused. One skill should do one thing well. If you find your instructions exceeding 40-50 lines, consider breaking the skill into two.
• Define output format explicitly. A template in the skill file ensures consistent results. Without it, Claude will choose a different format each time.
• Use defaults generously. Optional parameters with good defaults make skills easier to invoke. The most common invocation should need the fewest inputs.
• Write constraints as rules, not suggestions. "Stay under 300 words" works better than "try to keep it concise."
• Iterate based on output. Run the skill 3-4 times with different inputs after creating it. Tweak the instructions until the output is reliably good.
• Reference CLAUDE.md context. Your skill can say "use the company information from CLAUDE.md" to pull in project-level context without repeating it.