Back to Knowledge

Claude Skills Ecosystem

Four ways to extend Claude's capabilities — from quick commands to production-ready document processing. Know when to use each.

Official Documentation

Skills (Claude Code) API Skills Slash Commands

Quick Comparison

Claude Code Skills

Local files, auto-discovered

API Skills

Production ready, uploaded

Slash Commands

Manual trigger, explicit

Chained Skills

Multiple skills, one flow

1Claude Code Skills (Local Files)

Claude Code Skills are directories containing SKILL.md files that live in your project or home directory. Claude automatically discovers and applies them based on semantic matching.

Auto-Discovery

Claude reads your request and automatically applies relevant skills — no explicit invocation needed.

Progressive Disclosure

Only name/description load at startup. Full content loads when needed — keeps Claude fast.

Tool Restrictions

Limit which tools Claude can use without permission when the skill is active.

Multi-File Support

Include supporting docs, scripts, and templates alongside your SKILL.md file.

Real-Life Example: Code Review Consistency

Meet Sarah, a freelance developer who works with 5 different clients. Each client has different tech stacks, but she wants consistent, thorough PR reviews across all projects.

Problem: Manual reviews vary in quality. Sometimes she forgets to check security. Sometimes she skips performance analysis.

Solution: Creates a personal skill at ~/.claude/skills/pr-review/SKILL.md

Result: Every time she says "review this PR", Claude auto-applies the skill. Same checklist, same quality, across all 5 clients.

Example Skill Structure

~/.claude/skills/pr-review/SKILL.md

---
name: pr-review
description: Reviews PRs using comprehensive checklist. Use when reviewing code, pull requests, or diffs.
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash(git:*)
---

# PR Review Checklist

## Security
- [ ] No hardcoded secrets or API keys
- [ ] Input validation present
- [ ] Auth/authz checks in place

## Performance
- [ ] No N+1 queries
- [ ] Efficient data structures
- [ ] Appropriate caching

## Code Quality
- [ ] Clear variable names
- [ ] Functions under 50 lines
- [ ] Error handling present

Always explain WHY something is an issue, not just WHAT.

Storage Locations: Personal skills at ~/.claude/skills/ work across all projects. Project skills at .claude/skills/ are shared with your team via Git.

2API Skills (Console/Production)

API Skills are uploaded to Anthropic's platform and specified in your Messages API calls. Perfect for production applications where your users never interact with Claude directly — they just get results.

Cloud-Managed

Upload via API, manage versions, deploy updates — no local files required.

Pre-Built Skills

Anthropic provides xlsx, pptx, docx, and pdf skills ready to use.

Private to Workspace

Your custom skills are isolated to your organization — not shared publicly.

Production Ready

Built for scale — use in your SaaS product, internal tools, or automation pipelines.

Real-Life Example: SaaS Invoice Generator

Meet TechFlow, a project management SaaS with 5,000 customers. They need to generate professional Excel invoices with complex formulas, multiple sheets, and custom branding.

Problem: Manually creating Excel templates is brittle. Formula errors cause support tickets. Formatting inconsistencies look unprofessional.

Solution: Uses Anthropic's xlsx skill + custom validation skill uploaded via API.

Result: Users click "Generate Invoice" → Claude creates perfect Excel file with formulas, formatting, and validation. Zero manual work. 100% consistent.

Using API Skills

Python Example

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            # Anthropic's pre-built Excel skill
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            # Your custom validation skill
            {"type": "custom", "skill_id": "skill_01AbCdEfGh..."}
        ]
    },
    messages=[{
        "role": "user",
        "content": "Generate Q4 2024 invoice for TechFlow Inc with line items..."
    }],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

Pre-Built Skills Available: xlsx (Excel), pptx (PowerPoint), docx (Word), pdf (PDF forms). Upload custom skills via /v1/skills API endpoints.

3Slash Commands (Manual Triggers)

Slash Commands are simple .md files that you trigger explicitly by typing /command-name. Unlike Skills which auto-discover, commands require manual invocation — you're in control.

Explicit Invocation

You type /command when you want it. Not auto-discovered like Skills.

Single File

Just one .md file — simpler than Skills' directory structure.

Quick & Simple

Perfect for repeatable prompts you run frequently but want manual control over.

Shareable

Store in .claude/commands/ and share via Git, or keep personal at ~/.claude/commands/.

Real-Life Example: Quick Deploy Check

Meet Marcus, a backend engineer who deploys microservices 3-4 times per week. He has a mental checklist but sometimes forgets steps.

Problem: Forgotten pre-deploy checks cause production issues. Did he run tests? Check env vars? Verify migrations?

Solution: Creates .claude/commands/pre-deploy.md command.

Result: Before every deploy, types /pre-deploy. Claude runs the checklist. Consistent, thorough, zero forgotten steps.

Example Command

.claude/commands/pre-deploy.md

---
allowed-tools: Bash(git:*), Bash(npm:*)
argument-hint: [environment]
description: Pre-deployment sanity check
---

# Pre-Deploy Checklist

Run comprehensive pre-deployment checks for: $1

## Checks to Run

1. **Tests**: Run all tests, ensure 100% pass rate
2. **Linting**: Check for code style issues
3. **Environment Variables**: Verify all required vars are set
4. **Git Status**: Ensure working directory is clean
5. **Dependencies**: Check for security vulnerabilities
6. **Migrations**: Verify database migrations are up to date

Current branch: !git branch --show-current!
Last commit: !git log -1 --oneline!

Report any issues found. If all clear, confirm ready to deploy.

Key Difference: Commands are manual (/command) while Skills are automatic (semantic matching). Use commands when you want explicit control over when to trigger them.

4Chaining Skills Together

The real power emerges when you combine multiple skills into a single workflow. Load skills into Agents, chain them in pipelines, or let Claude use multiple skills in one task.

Real-Life Example: Full-Stack Code Review Agent

Meet DevTeam Inc, a 15-person engineering team. They want consistent, comprehensive code reviews covering security, performance, and team conventions.

The Agent:

code-reviewer - Handles the review process, reads files, analyzes code

Loaded Skills:

• security-checklist - 20-point security audit

• performance-patterns - Database query optimization, caching strategies

• team-conventions - Error handling, naming, structure

Result:

Every PR gets the same thorough review. New team members learn conventions. Senior engineers save time. Quality is consistent.

Agent Configuration

.claude/agents/code-reviewer.md

---
name: code-reviewer
description: Reviews code with comprehensive security, performance, and convention checks
model: sonnet
tools:
  - Read
  - Grep
  - Glob
  - Bash(git:*)
skills:
  - security-checklist
  - performance-patterns
  - team-conventions
---

# Code Reviewer Agent

You are a senior code reviewer for DevTeam Inc.

## Your Job

1. Thoroughly review the specified files
2. Apply ALL loaded skills (security, performance, conventions)
3. Provide actionable, specific feedback
4. Explain WHY issues matter, not just WHAT they are

Be thorough but constructive. Help developers improve.

Real-Life Example: Documentation Pipeline

Meet OpenSource Co, maintaining a large open-source library. They need automated API documentation generated from code, formatted consistently, and exported as PDFs for customers.

Step 1: Code Analysis

Skill: code-analyzer - Extracts function signatures, JSDoc comments, types

Step 2: Markdown Generation

Skill: doc-writer - Converts analysis to structured markdown with examples

Step 3: PDF Export

API Skill: pdf - Formats as professional PDF with branding

Result:

One command generates complete, professional API docs. Runs in CI/CD on every release. Zero manual formatting.

Pro Tip: Think of Agents as who does the work, Skills as what they know. Combine them for powerful, consistent workflows that would take hours manually.

?When to Use What

Ask yourself these questions to decide which method fits your use case:

"Building a product or API for production users?"

Use API Skills — upload skills, call via Messages API, users never see Claude directly

"Improving my personal development workflow?"

Use Claude Code Skills (Personal) — store at ~/.claude/skills/, works across all your projects

"Enforcing team standards across the codebase?"

Use Claude Code Skills (Project) — store at .claude/skills/, share via Git, everyone on the team gets them

"Want a quick prompt I can run when I need it?"

Use Slash Command — simple .md file, type /command to trigger manually

"Complex task needing isolation with multiple standards?"

Use Agent with Skills Loaded — isolated context, multiple skills applied, comprehensive workflow

Skills Shine — Single Task Excellence

Skills excel at doing one thing perfectly, every time. No variance, no "forgot to check this", no inconsistency. Here's where they shine:

Commit Messages

Same format every time, no variance.

feat(auth): add OAuth login ✓

Not: "added login", "new auth", "implement login feature"

SQL Queries

Always follows your schema patterns.

Proper indexes, no N+1, correct joins ✓

Not: inefficient queries, wrong table names, missing indexes

Error Messages

Consistent, user-friendly format.

Action failed. What to do next. ✓

Not: cryptic errors, technical jargon, no guidance

API Responses

Matches your exact response structure.

{data, meta, errors} ✓

Not: varying structures, missing fields, wrong types

The Pattern: Wherever you need consistency, standards, or no variance — that's where Skills shine. One skill = one task done perfectly every time.

Ready to build your skills?

Learn how to create custom agents and skills, or explore the differences between them.

Create Agents & Skills Agents vs Skills PRO Tips