Skills Overview

A comprehensive guide to setup, usage, and best practices across platforms

October 2025 Cardsite 15 min read

Executive Summary

Key Insight

Claude Skills represent a paradigm shift from prompt engineering to capability packaging. Launched October 16, 2025, they enable organizations to transform Claude from a general-purpose assistant into a specialized agent with composable, reusable capabilities.

Claude Skills are self-contained capability packages that extend Claude's functionality across all Anthropic platforms. Unlike traditional prompts, Skills combine instructions, executable code, and resources in a progressive disclosure architecture that loads only what's needed, when it's needed.

Core Advantages

Scroll
Composable
Skills automatically stack together for complex workflows without manual configuration
Portable
Same format works seamlessly across Claude.ai, Claude Code, and API
Efficient
Each skill uses only 30-50 tokens until loaded, keeping context windows clear
Powerful
Include executable code for deterministic operations beyond LLM capabilities
Discoverable
Claude autonomously decides when to invoke them based on task context
Secure
Sandboxed execution environment with controlled permissions and access

What Are Claude Skills?

A Skill is a directory containing a SKILL.md file with organized instructions, scripts, and resources that Claude can discover and load dynamically to perform specific tasks. Think of Skills as onboarding materials for specialized capabilities.

New Skills Available
Anthropic has released official skills for document processing (Excel, PowerPoint, Word, PDF). Install them now to enhance Claude's capabilities.

Anatomy of a Skill

my-skill/
├── SKILL.md           # Required: Core instructions with YAML frontmatter
├── resources/         # Optional: Supporting documentation
│   ├── reference.md
│   └── examples.md
├── scripts/           # Optional: Executable helpers
│   └── helper.py
└── templates/         # Optional: Reusable templates
    └── template.txt

SKILL.md Structure

---
name: brand-guidelines
description: Apply Acme Corp brand guidelines to presentations and documents
version: 1.0.0
---

# Brand Guidelines

## Instructions
Provide clear, step-by-step guidance for Claude.
Progressive Disclosure Architecture

Skills use a two-level loading system:

  1. Discovery Phase: Claude preloads only the name and description of every installed skill
  2. Loading Phase: When matched, Claude reads the full SKILL.md and references additional files as needed

This architecture keeps Claude fast while maintaining access to specialized expertise.

SKILL.md vs CLAUDE.md

Understanding the difference between these two file types is essential for effective Claude usage. They serve different purposes at different system levels.

SKILL.md

Packaged Capabilities

Task-specific expertise that can be invoked on-demand

  • Lives in skill directories
  • Requires precise description
  • Can include Python/JS scripts
  • Portable across platforms
  • Model-invoked autonomously
  • Uses 30-50 tokens until loaded
CLAUDE.md

Project Memory

Environment configuration and persistent context

  • Lives in project root
  • Always loaded at session start
  • No executable code allowed
  • Claude Code specific
  • Treated as system rules
  • Higher instruction priority

Typical CLAUDE.md Structure

# Tech Stack
- Framework: Next.js 14
- Language: TypeScript 5.2
- Styling: Tailwind CSS 3.4

# Commands
- `npm run dev`: Start development server
- `npm run build`: Build for production

Deployment Levels

Skills can be deployed at different scopes depending on your needs. Choose the right level based on your workflow and team structure.

Personal Skills (Global)

Available across all your projects for individual productivity enhancements.

$ mkdir -p ~/.claude/skills/my-skill 
echo '---
name: my-skill
description: My personal workflow helper
---' > ~/.claude/skills/my-skill/SKILL.md

Project Skills (Version Controlled)

Team-shared capabilities that sync automatically through Git.

  1. Create skill directory
    $ mkdir -p .claude/skills/database-helper
  2. Add to version control
    $ git add .claude/skills/
  3. Commit and push
    $ git commit -m "Add database helper skill"
  4. Team gets updates automatically
    When teammates pull changes, they automatically receive the new skill—no manual installation needed.

Platform Comparison

Claude Skills work across all Anthropic platforms, but implementation details vary. Choose the platform that best fits your workflow and deployment needs.

Platform Skill Format Installation Sharing Best For
Claude.ai ZIP upload Manual Individual only Quick access, document work, no installation needed
Claude Desktop ZIP upload Manual Individual only Native app experience, offline capability
Claude Code Directory-based Git Team (automatic) Codebase work, team collaboration, version control
Claude API ZIP/Inline/IDs Programmatic Centralized Production apps, enterprise deployment, custom agents
Recommendation

For team collaboration, use Claude Code with Git-based skill distribution. For production systems, use the API with centralized skill management. Individual users should start with Claude.ai for the simplest onboarding experience.

Setup Guide

Claude.ai (Web Application)

  1. Navigate to Skills settings
    Go to Settings → Capabilities → Skills
  2. Enable Skills feature
    Toggle "Enable Skills" switch to on
  3. Create or upload skill
    Click "Create Skill" for guided wizard or "Upload" for existing skills
  4. Test and activate
    Test with example prompts to verify functionality

Claude Code (CLI)

Requirements

Node.js 18 or later is required. Verify with node --version

Installation

$ npm install -g @anthropic-ai/claude-code

Verification

$ claude --version

Project Initialization

# Navigate to your project
cd your-project

# Start Claude Code
claude

# Generate CLAUDE.md
/init
What Gets Created
  • CLAUDE.md - Project configuration and context
  • .claude/ - Directory for commands and skills
  • .claude/commands/ - Custom slash commands
  • .claude/skills/ - Project-specific skills

Best Practices

Writing Effective SKILL.md Files

Description is Critical

The description field determines when Claude invokes your skill. Make it specific and include key terms users would mention.

Structure for Scale

When SKILL.md becomes unwieldy, split content into separate files for better organization and maintainability.

Pro Tip

Use progressive disclosure: keep SKILL.md concise with core instructions, then reference detailed documentation in separate resource files. This keeps token usage low until full context is needed.

Security Considerations

Critical Security Warning

Skills can execute arbitrary code in Claude's environment. Only install Skills from trusted sources. Malicious Skills can exfiltrate data, manipulate outputs, or compromise your workflow.

Primary Risks

  • Prompt Injection: Skills can be manipulated through crafted prompts
  • Data Exfiltration: Malicious skills can leak sensitive information
  • Malicious Dependencies: Third-party packages may contain harmful code
Best Practice

Always review skill source code before installation. Check for network calls, file operations, and external dependencies. For enterprise deployments, establish a security review process and maintain an approved skill catalog.