Skip to content

Instantly share code, notes, and snippets.

@stevenringo

stevenringo/claude-skills.md

Last active November 17, 2025 13:02
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save stevenringo/d7107d6096e7d0cf5716196d2880d5bb to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save stevenringo/d7107d6096e7d0cf5716196d2880d5bb to your computer and use it in GitHub Desktop.
Download ZIP
About Claude Skills - A comprehensive guide
Raw
claude-skills.md

About Claude Skills

A comprehensive guide to Claude Skills and how they compare to other agentic tools in Claude Code.

Table of Contents

What Are Claude Skills?

Claude Skills are modular capabilities that extend Claude's functionality in Claude Code. They package expertise into discoverable, reusable components through organized folders containing instructions, scripts, and resources.

Core Characteristics

  • Modular: Self-contained units of expertise
  • Discoverable: Claude automatically finds and uses them
  • Portable: Work across Claude.ai, Claude Code, and API
  • Composable: Multiple skills work together seamlessly
  • Efficient: Load only when needed (progressive loading)

How They Work

Skills operate through model invocation - Claude autonomously determines when to use them based on:

  • Your request/query
  • The skill's description field
  • Current conversation context

No explicit commands needed - just describe what you want to do naturally.

Skills Deep Dive

How Are Skills Modular?

Skills are self-contained, reusable units of expertise. Each skill is isolated in its own directory with its own instructions and resources.

Benefits:

  • Separate skills for different concerns (PDF processing vs code review vs commit messages)
  • Each skill works independently
  • Add/remove/update skills without affecting others
  • Teams can share specific skills without sharing entire setup

Example structure:

~/.claude/skills/          # Personal skills
├── pdf-extraction-skill/
├── code-review-skill/
└── tdd-workflow-skill/

.claude/skills/            # Project skills (shared via git)
└── team-standards-skill/

How Are Skills Packaged?

Skills are packaged as organized directories containing:

Required:

  • SKILL.md - Main instructions with YAML frontmatter

Optional:

  • Supporting files (scripts, templates, docs)

Example structure:

my-skill/
├── SKILL.md              # Required: main instructions
├── reference.md          # Optional: additional docs
├── examples/             # Optional: example files
└── scripts/              # Optional: helper scripts

Distribution options:

  • Manual: Copy directory to skills folder
  • Git: Share via .claude/skills/ in your repo
  • Plugins: Bundle skills into a plugin for marketplace distribution

What Are Supporting Files?

Supporting files are optional additional resources that complement the main SKILL.md instructions.

Types:

  • Documentation: reference.md, api-docs.md, examples.md
  • Scripts: Python/bash utilities the skill might need
  • Templates: Boilerplate code, config files, document templates
  • Examples: Sample inputs/outputs to guide Claude

Why use them?

  • Keep the main SKILL.md focused and concise
  • Provide reference material Claude can consult when needed
  • Include reusable code or templates

How Does Claude Decide When to Use Skills?

The mechanism:

  1. You make a request (e.g., "Extract data from this PDF")
  2. Claude reads all available skill descriptions (from SKILL.md frontmatter)
  3. Claude semantically matches your request against descriptions
  4. Claude invokes relevant skills automatically

Key characteristics:

✓ Semantic understanding of intent (not keyword matching) ✓ Contextual relevance assessment ✓ Autonomous activation (no manual trigger needed)

✗ Not keyword matching (though mentioning "PDF" helps) ✗ Not rule-based (no if/then logic) ✗ Not manual (you don't type /use-skill)

What Is "Contextually Triggered"?

Contextually triggered means skills activate based on the meaning and context of your request, not explicit commands.

Example scenarios:

Your Request Context Skill Triggered
"Extract text from invoice.pdf" PDF work PDF skill ✓
"Fill out this form" Document editing Form-filling skill ✓
"Help me write a function" Coding Not PDF skill ✗

In practice:

  • No need to remember skill names or commands
  • Skills work like "invisible assistants" that step in when relevant
  • Claude considers the entire conversation context, not just the current message

What Does "Progressively Loaded" Mean?

Progressive loading means Claude only reads supporting files when actually needed, not upfront.

How it works:

  1. Initial load: Claude reads just the SKILL.md description (lightweight)
  2. Skill activated: Claude reads the main SKILL.md instructions
  3. As needed: Claude reads supporting files only if referenced or required

Why this matters:

  • Token efficiency: Doesn't waste context on unused files
  • Performance: Faster startup and skill discovery
  • Scalability: You can have many skills without bloating context

Example:

pdf-skill/
├── SKILL.md              ← Always read on activation
├── api-reference.md      ← Only read if Claude needs API details
├── examples/             ← Only read if Claude needs examples
└── scripts/              ← Only loaded if execution needed

Plugins and Distribution

What Are Plugins?

Plugins are extension packages for Claude Code that can bundle multiple components:

What they can contain:

  • ✓ Skills (autonomous capabilities)
  • ✓ Slash commands (manual shortcuts)
  • ✓ Hooks (event triggers)
  • ✓ MCP servers (external integrations)
  • ✓ Custom agents

Relationship to Skills

  • Skills are one component that can be packaged in a plugin
  • A plugin can have multiple skills in its skills/ directory
  • When you install a plugin, its skills become available to Claude

Example: The document-skills plugin contains:

  • pdf skill
  • xlsx skill
  • docx skill
  • pptx skill

Can Plugins Be Packaged for Distribution?

Yes! Plugins have multiple distribution methods:

1. Marketplaces (Primary method):

  • Public marketplaces (like an app store)
  • Private/organizational marketplaces
  • Users can browse and install with claude plugin install <name>

2. Team/Repo Level:

  • Configure in .claude/settings.json in your repo
  • Team members automatically see plugins when they trust the repo
  • Ensures consistent tooling across the team

3. Local Development:

  • Create a local marketplace directory
  • Use a manifest file to reference your plugins
  • Good for testing before publishing

Requirements for distribution:

  • Documentation (README, usage examples)
  • Semantic versioning in the manifest
  • Proper manifest configuration

Writing Effective Skill Descriptions

The description field in your skill's YAML frontmatter is critical for discovery. It drives Claude's decision to use the skill.

The Formula

The description field should have TWO components:

1. WHAT the skill does (capabilities)

  • Be specific and concrete
  • List key functions
  • Mention technologies/file types

2. WHEN to use it (triggers)

  • Keywords users might mention
  • Scenarios that should activate it
  • Types of tasks it handles

Template:

"[WHAT it does]. Use when [WHEN to trigger]."

Good Examples

✓ Excellent:

description: "Extract text and tables from PDF files, fill forms, merge documents, and handle forms. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction."

✓ Good:

description: "Complete browser automation with Playwright. Use when user wants to test websites, automate browser interactions, validate web functionality, or perform any browser-based testing."

Bad Examples

✗ Too vague:

description: "Helps with documents"

Missing: What kind of documents? What operations?

✗ No triggers:

description: "Extracts data from PDFs"

Better with: "Use when user mentions PDFs or data extraction"

✗ Too broad:

description: "Does everything with files"

Claude won't know when to use it

Pro Tip

Think about what words/phrases a user would naturally use when they need this skill, and include those in the WHEN section.

Creating Skills with skill-creator

The Meta Skill for Building Skills

Claude Code includes a pre-loaded meta skill called skill-creator that helps you create new skills through interactive conversation. This is a skill that teaches Claude how to build more skills!

What Is skill-creator?

skill-creator is a built-in skill that provides:

  • Interactive guidance through the skill creation process
  • Automatic folder structure generation
  • SKILL.md file formatting and best practices
  • Resource bundling assistance

Think of it as: Your personal guide for building effective Claude skills.

How to Use skill-creator

The skill activates automatically when you express intent to create a new skill. No special commands needed!

Simple workflow:

  1. Express your intent

    "I want to create a skill for managing API documentation"
"Help me build a skill that enforces our security review checklist"
"Create a skill for our brand guidelines"

  2. Claude activates skill-creator automatically

    • Asks clarifying questions about your workflow
    • Understands the problem you're trying to solve
    • Identifies what should trigger the skill

  3. Claude generates the skill structure

    • Creates the folder structure
    • Writes the SKILL.md with proper YAML frontmatter
    • Suggests supporting files if needed
    • Bundles relevant resources

  4. Review and refine

    • Claude shows you the proposed skill
    • You provide feedback
    • Claude adjusts based on your input

Example Interaction

You: "I want to create a skill that helps enforce our API design guidelines"

Claude (skill-creator activated):
"I'll help you create that skill. Let me ask a few questions:

1. What are the key guidelines that should be checked?
2. When should this skill activate? (e.g., when reviewing API code,
   designing new endpoints, etc.)
3. Do you have existing documentation I should reference?
4. Should this include code examples or just guidelines?"

You: "We follow REST principles, require OpenAPI specs, and have
specific naming conventions. It should activate when someone is
designing or reviewing APIs."

Claude:
"Perfect! I'll create a skill called 'api-guidelines' with:
- SKILL.md containing REST principles and naming conventions
- Reference to OpenAPI spec requirements
- Examples of good vs bad API designs
- Triggered when users mention 'API', 'endpoint', 'REST', or 'OpenAPI'

Here's the structure..."

[Claude generates the complete skill]

What skill-creator Creates

Automatic generation includes:

  1. Folder structure

    ~/.claude/skills/your-skill-name/
├── SKILL.md
├── reference.md (if needed)
└── examples/ (if appropriate)

  2. SKILL.md with proper format

    ---
name: your-skill-name
description: "What it does. Use when [triggers]."
---

# Skill Instructions

[Detailed instructions Claude generated based on your input]

  3. Supporting files

    • Documentation references
    • Code examples
    • Templates or checklists
    • Scripts (if applicable)

Benefits of Using skill-creator

✓ Saves time - No need to manually create folder structure ✓ Best practices - Ensures proper YAML frontmatter and description format ✓ Interactive - Asks the right questions to capture your workflow ✓ Educational - Teaches you what makes an effective skill ✓ Iterative - Easy to refine based on feedback

Community Meta-Skills

Beyond the built-in skill-creator, the community has created additional meta-skills:

agent-skill-creator:

skill-builder:

Tips for Working with skill-creator

Be specific about:

  • The problem you're solving
  • When the skill should activate (triggers)
  • What outputs/behaviors you expect
  • Any existing documentation or examples

Example:

  • ❌ "Create a skill for code review"
  • ✅ "Create a skill that checks Python code for our team's security requirements: input validation, SQL injection prevention, and secrets management. Should activate when reviewing Python pull requests."

Let Claude ask questions:

  • skill-creator will guide you through the process
  • Answer its questions to refine the skill
  • Don't try to provide everything upfront

Iterate and refine:

  • Review the generated skill
  • Test it in practice
  • Ask Claude to adjust based on real usage
  • Skills can be updated anytime

Manual Creation Still Possible

You can still create skills manually if you prefer:

  1. Create folder in ~/.claude/skills/
  2. Write SKILL.md with YAML frontmatter
  3. Add supporting files

But skill-creator makes this much easier and ensures best practices!

Sharing Skills with Your Team

Skills are designed to be shared across your team and organization. The sharing method depends on which Claude platform you're using.

For Claude Code (Git-based Sharing)

Recommended approach: Commit skills to your project repository.

How it works:

  1. Create project skills

    • Add skills to .claude/skills/ directory in your project
    • Each skill is a folder with SKILL.md and supporting files

  2. Commit to version control

    git add .claude/skills/
git commit -m "Add team skills for API review and testing"
git push

  3. Team members get skills automatically

    • When teammates pull the repository, skills are immediately available
    • No manual installation needed
    • Skills update automatically with git pulls

Benefits:

  • ✓ Skills travel with the codebase
  • ✓ Version controlled like any other code
  • ✓ Team workflows and conventions stay in sync
  • ✓ Easy to review changes via pull requests

Example structure:

your-project/
├── .claude/
│   └── skills/
│       ├── api-review-skill/
│       │   └── SKILL.md
│       ├── security-checklist/
│       │   ├── SKILL.md
│       │   └── checklist.md
│       └── testing-standards/
│           └── SKILL.md
├── src/
└── package.json

For Claude.ai and Desktop (.zip File Sharing)

For organization-wide distribution, skills can be packaged as .zip files.

How it works:

  1. Create the skill folder

    my-skill/
├── SKILL.md
└── reference.md (optional)

  2. Package as .zip

    • Compress the skill folder into a .zip file
    • Ensure SKILL.md is at the root of the zip

  3. Share with your team

    • Claude.ai: Users upload via Settings > Features
    • Claude Desktop: Upload via settings interface
    • Note: Skills uploaded this way are private to individual accounts

  4. Team members install individually

    • Each person uploads the .zip to their own account
    • Skills become available immediately after upload

Platform differences:

  • Individual accounts: Skills are private, need individual upload
  • Organization API: Skills can be shared organization-wide programmatically
  • Claude Code: Doesn't use .zip files; uses filesystem-based sharing

For Claude API (Organization-wide)

Enterprise approach: Deploy skills organization-wide via API.

How it works:

  1. Create skills following API documentation
  2. Upload skills via API endpoints
  3. Skills automatically available to all organization members
  4. Centrally managed and updated

Benefits:

  • ✓ Single source of truth
  • ✓ Automatic distribution to all users
  • ✓ Centralized management
  • ✓ No manual installation by team members

Via Plugin Distribution

For public/community sharing: Package skills as plugins.

How it works:

  1. Create a plugin containing your skills

    my-plugin/
├── manifest.json
└── skills/
    ├── skill-one/
    │   └── SKILL.md
    └── skill-two/
        └── SKILL.md

  2. Publish to marketplace

    • Add to public marketplace (e.g., GitHub)
    • Or create private organizational marketplace

  3. Team installs via plugin commands

    /plugin marketplace add your-org/your-marketplace
/plugin install your-plugin-name

Benefits:

  • ✓ Versioned releases
  • ✓ Easy updates
  • ✓ Can include multiple skills
  • ✓ Discoverable via plugin interface

Best Practices for Team Sharing

Choose the right method:

Platform Sharing Method Best For
Claude Code Git repository (.claude/skills/) Development teams, project-specific skills
Claude.ai .zip files Individual contributors, small teams
Claude API API deployment Enterprise, organization-wide standards
Any platform Plugin marketplace Public sharing, versioned distribution

Tips:

  1. Document your skills

    • Add README explaining what each skill does
    • Include examples of when to use them
    • Document any dependencies

  2. Use clear naming

    • api-review-standards not skill1
    • Name reflects purpose and scope

  3. Version control

    • Tag releases for stability
    • Document changes in skill updates
    • Test before sharing with team

  4. Keep skills focused

    • One skill = one specific expertise
    • Easier to share and maintain
    • Team can pick what they need

  5. Review as a team

    • Use pull requests for Claude Code skills
    • Get feedback before organization-wide deployment
    • Iterate based on usage

Web vs CLI Compatibility

Can Skills Be Used Interchangeably?

YES and NO - it depends on the type:

According to Anthropic:

  • Skills are designed to be "portable" - they function identically across:
    • Claude.ai web chatbot
    • Claude Code CLI
    • Claude API
    • Mobile apps

However, there's a distinction:

Claude Code Skills (local CLI):

  • CLI-specific
  • Located in ~/.claude/skills/ or .claude/skills/
  • Model-invoked during coding tasks
  • Can include scripts and local file resources

Claude.ai Skills (web/API):

  • Managed through Claude Console
  • Organization-wide deployment
  • More focused on knowledge/procedures than local scripts

Bottom line: The concept is portable, but the implementation differs slightly. A skill written for Claude Code might need adaptation for the web chatbot and vice versa, especially if it relies on local file access or CLI tools.

Finding More Skills

There's a thriving community ecosystem of skills and plugins available. Here are the main directories and repositories to explore.

Official Anthropic Repository

GitHub: https://github.com/anthropics/skills

What it contains:

  • Document Skills (production-ready): Word, PDF, PowerPoint, Excel manipulation
    • Create, edit, and analyze documents
    • Support for tracked changes, comments, formatting preservation
  • Example Skills organized in four categories:
    • Creative & Design: Algorithmic art (p5.js), canvas design, Slack GIFs
    • Development: Artifact builder, MCP server creation, Playwright testing
    • Enterprise: Brand guidelines, internal communications, theme factory
    • Document processing: Comprehensive file manipulation capabilities

How to install:

# For Claude Code
/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills

Also available on:

  • Claude.ai (paid users can upload custom skills)
  • Claude API (via Skills API guide)

Why use it:

  • ✓ Official, production-ready skills
  • ✓ Well-documented and maintained
  • ✓ Reference implementations for creating your own
  • ✓ Trusted source from Anthropic

Community Marketplaces

1. Claude Skills Marketplace

Website: https://skillsmp.com

Overview:

  • Independent community marketplace (not affiliated with Anthropic)
  • Auto-indexes public skills from GitHub repositories
  • Currently hosts 2,277 free, open-source skills

Categories (with skill counts):

  • Developer Tools (564 skills)
  • Web & App Development (398 skills)
  • Testing & QA (240 skills)
  • Documents & Content (211 skills)
  • Database & Data (190 skills)
  • API & Backend (173 skills)
  • DevOps & Infrastructure (125 skills)
  • Security & Monitoring (83 skills)

Features:

  • Search by keyword
  • Sort by popularity (GitHub stars) or recent updates
  • Quality filtering (minimum 2-star repos)
  • Category and subcategory browsing
  • Direct links to GitHub repositories

How to install: Three methods available:

  1. Personal skills: Copy to ~/.claude/skills/ directory
  2. Project skills: Add to .claude/skills/ and commit to git
  3. Plugin skills: Use /plugin commands for installation

Best for:

  • Discovering new skills by category
  • Finding community-tested solutions
  • Browsing curated, quality-filtered skills
  • Quick access to GitHub repositories

2. Claude Code Skills Marketplace

Website: https://claude-plugins.dev/skills

Overview:

  • Community-maintained marketplace for Claude Skills
  • Auto-indexes public skills from GitHub
  • Currently hosts 7,453 skills across various domains

Categories include:

  • Development: Next.js, Tailwind CSS, shadcn/ui, async Python patterns
  • Architecture: System design, backend patterns, API design principles
  • Productivity: Brainstorming, systematic debugging, prompt engineering
  • Specialized: PDF processing, financial modeling, scientific writing, marketing

Features:

  • Centralized registry for easy discovery
  • Each skill listing includes:
    • Description and use cases
    • GitHub repository link
    • Installation instructions
    • Download/fork counts
  • Built with Val Town and Claude Code

How to browse:

  • Visit "Browse Skills" section
  • Filter by domain/category
  • Search by keyword or technology
  • Direct GitHub integration

Best for:

  • Largest collection of skills (7,453+)
  • Finding specialized domain skills
  • Technology-specific searches
  • Active community contributions

Notable GitHub Repositories

obra/superpowers:

  • https://github.com/obra/superpowers
  • Core skills library with 20+ battle-tested skills
  • Includes: TDD workflows, debugging patterns, collaboration tools
  • Features specialized commands: /brainstorm, /write-plan, /execute-plan
  • Focus on software engineering best practices

travisvn/awesome-claude-skills:

Other valuable collections:

How to Discover and Install

Within Claude Code:

# Browse available plugins and skills
/plugin

# Add a marketplace
/plugin marketplace add <org>/<repo>

# Install specific skill or plugin
/plugin install <skill-name>

# Example: Install Anthropic's document skills
/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills

From community marketplaces:

  1. Browse https://skillsmp.com or https://claude-plugins.dev/skills
  2. Find a skill you want
  3. Click through to the GitHub repository
  4. Follow installation instructions (usually involves cloning or downloading)
  5. Add to ~/.claude/skills/ (personal) or .claude/skills/ (project)

Tips for choosing skills:

✓ Check GitHub stars and recent activity ✓ Read the SKILL.md to understand what it does ✓ Look for clear documentation ✓ Verify it matches your use case ✓ Start with official or highly-rated skills ✓ Test in a personal project before team deployment

Comparison: Which Directory to Use?

Directory Skills Best For Strength
github.com/anthropics/skills Official examples Production-ready, trusted skills Quality, support
skillsmp.com 2,277 Category browsing, quality filtering Curated selection
claude-plugins.dev/skills 7,453 Largest collection, specialized needs Breadth of options
GitHub repos Various Specific use cases, learning Direct source code

Recommendation:

  • Start with: Anthropic's official repository for core document skills
  • Explore: SkillsMP for curated, quality-filtered options
  • Deep dive: claude-plugins.dev for specialized or niche skills
  • Learn from: GitHub repos to see how skills are built

When to Use Which Tool

Use SKILLS When

Criteria:

  • ✓ Task requires specialized knowledge/expertise
  • ✓ You want automatic activation (no manual trigger)
  • ✓ Need to share complex workflows across team
  • ✓ Requires composability with other capabilities
  • ✓ May need executable scripts/code

Examples:

Example 1: PDF Processing

  • Scenario: Your team frequently works with PDFs (extraction, form-filling, merging)
  • Why skill? Claude automatically recognizes PDF work and loads the skill
  • Not slash command because: Too many variations to create individual commands
  • Not CLAUDE.md because: Too complex for just instructions
  • Not MCP because: No external service needed

Example 2: Code Review Standards

  • Scenario: Your company has specific code review guidelines
  • Why skill? Claude automatically applies standards when reviewing code
  • What it includes: Review checklist, security patterns, style guide
  • User experience: Just say "review this PR" - no need to remember to trigger it

Example 3: Brand Guidelines Enforcement

  • Scenario: Creating marketing materials with brand standards
  • Why skill? Automatic application of color schemes, tone, formatting
  • Could use CLAUDE.md but: Skill is more modular and reusable

Use SLASH COMMANDS When

Criteria:

  • ✓ User needs explicit control over when it runs
  • ✓ Simple prompt expansion (no complex logic)
  • ✓ Repetitive, predictable workflows
  • ✓ Quick shortcuts for common tasks

Examples:

Example 1: Git Commits

  • Command: /commit
  • Why command? You want to decide exactly when to commit
  • Why not skill? Don't want auto-commits - too dangerous!
  • What it does: Expands to "Review changes, write commit message, create commit"

Example 2: Create Pull Request

  • Command: /pr
  • Why command? Explicit action you trigger intentionally
  • Why not skill? Need control over timing
  • What it does: Analyzes changes, writes PR description, creates PR

Example 3: Run Tests

  • Command: /test
  • Why command? You decide when to run tests
  • Why not skill? Running tests has side effects; needs explicit trigger

Use MCP SERVERS When

Criteria:

  • ✓ Need to integrate external services/tools
  • ✓ Access remote data (databases, APIs)
  • ✓ Connect to issue trackers, monitoring tools
  • ✓ Require persistent connections or credentials

Examples:

Example 1: Database Access

  • MCP Server: PostgreSQL connector
  • Why MCP? Need live database queries
  • Why not skill? Skills can't maintain DB connections
  • What it enables: "Show me users who signed up last week" → queries DB directly

Example 2: Jira/Linear Integration

  • MCP Server: Issue tracker connector
  • Why MCP? Need to read/write issues in external system
  • Why not skill? Skills are local; can't call external APIs directly
  • What it enables: "Implement feature from issue #123" → fetches issue details

Example 3: Figma Integration

  • MCP Server: Figma connector
  • Why MCP? Access design files and specs
  • Why not skill? Designs live in external service
  • What it enables: "Build this component from Figma" → fetches design specs

Example 4: Monitoring/Observability

  • MCP Server: DataDog/Grafana connector
  • Why MCP? Pull live metrics and logs
  • Why not skill? Data is external
  • What it enables: "Debug the latency spike at 3pm" → analyzes monitoring data

Use CLAUDE.md When

Criteria:

  • ✓ Project-wide rules/preferences
  • ✓ Simple instructions/guidelines
  • ✓ Coding standards and conventions
  • ✓ Always-on context (not conditional)

Examples:

Example 1: Python Project Standards

# CLAUDE.md

- Use uv for dependency management
- Prefer Polars over Pandas
- Add type hints to all functions
- Use pytest for testing
  • Why CLAUDE.md? Simple rules, always applicable
  • Why not skill? Too simple to need a skill
  • Why not command? Should always be active

Example 2: Team Conventions

# CLAUDE.md

- Never commit directly to main
- Use conventional commits format
- Update CHANGELOG.md on each PR
  • Why CLAUDE.md? General rules for all work
  • Why not skill? No specialized knowledge needed
  • Effect: Claude always follows these rules

Example 3: Tech Stack Preferences

# CLAUDE.md

- Frontend: React + TypeScript + Tailwind
- Backend: Node.js + Express + PostgreSQL
- Testing: Jest + Playwright
  • Why CLAUDE.md? Project context, always relevant
  • Why not skill? Not task-specific
  • Effect: Claude uses correct stack automatically

Comparison Overview

Key Differences Summary

Feature Activation Complexity Scope Best For
Skills Autonomous Medium-High Specialized workflows Reusable expertise, complex tasks
Slash Commands Manual Low Prompt shortcuts Repetitive commands, quick tasks
MCP Servers Autonomous High External integrations Databases, APIs, external tools
CLAUDE.md Always-on Low Persistent context Rules, standards, preferences

Decision Matrix

Need Solution Example
Complex expertise, auto-triggered Skill PDF processing, code review, TDD workflow
Simple shortcut, manual trigger Slash Command /commit, /pr, /test
External data/service access MCP Server Database, Jira, Figma, monitoring
Project-wide rules CLAUDE.md Coding standards, tech stack, conventions
Combination needed Multiple tools MCP (Jira) + Skill (feature dev) + CLAUDE.md (standards)

Mental Model

  • CLAUDE.md = "Here are my rules and preferences"
  • Slash Commands = "Quick shortcuts I trigger manually"
  • Skills = "Specialized expertise Claude uses when relevant"
  • MCP Servers = "External tools and data Claude can access"

Real-World Example

Scenario: Building a New Feature

How all four tools work together:

  1. CLAUDE.md: Ensures code follows team standards

    • Python + uv for dependencies
    • Type hints required
    • Polars preferred over Pandas

  2. MCP Server (Jira): Fetches feature requirements

    • Claude reads issue description
    • Pulls acceptance criteria
    • Checks linked design files

  3. Skill (TDD): Automatically applies test-driven development

    • Writes tests first
    • Implements minimal code to pass
    • Refactors with confidence

  4. Slash Command: Manual control for final steps

    • /test - Run test suite when ready
    • /commit - Create commit with proper message
    • /pr - Generate pull request

User experience:

You: "Implement feature from issue #123"

Claude (automatically):
- Reads CLAUDE.md for project standards
- Uses Jira MCP to fetch issue details
- Activates TDD skill based on project type
- Writes tests, implements feature
- Suggests running /test when done

You: "/test"
Claude: Runs tests, all pass

You: "/commit"
Claude: Creates semantic commit

You: "/pr"
Claude: Generates PR with proper description

Each tool has a specific role, working together seamlessly!

Summary

Claude Skills are powerful, modular capabilities that:

  • Extend Claude's expertise in specialized domains
  • Activate automatically based on context
  • Share easily across teams via git
  • Compose with other tools (MCP, commands, CLAUDE.md)
  • Scale efficiently through progressive loading
  • Can be created easily using the built-in skill-creator meta skill

Choose the right tool for the job, and combine them when needed for maximum effectiveness!

Getting started with skills:

  1. Explore existing skills from marketplaces and GitHub
  2. Use skill-creator to build your first custom skill
  3. Share team skills via .claude/skills/ in your repo
  4. Combine with MCP, slash commands, and CLAUDE.md for powerful workflows
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment