Claude Skills: A Practical Guide

Quick Recap

In the previous article, we covered the core concepts of Skills: reusable playbooks for AI assistants that achieve exceptional token efficiency through a progressive disclosure architecture, with three key strengths — efficiency, composability, and portability. This article takes a hands-on approach to help you understand how Skills differ from other features, learn to enable, install, and create Skills, and master best practices while avoiding common pitfalls.

Feature Comparison

The Claude ecosystem offers multiple features, and it can be confusing to tell them apart at first. The table below provides a quick overview:

Skills vs MCP

This is the most common source of confusion. The core distinction: MCP connects Claude to data; Skills teach Claude how to process data. They complement rather than replace each other.

Once you understand this distinction, you'll know when to use each one. Use MCP when you need to query databases, call APIs, or access cloud services. Use Skills when you need to follow a specific writing style, execute standardized workflows, or reuse domain expertise.

The best practice is to combine both: use MCP to connect to your CRM system and pull customer data, then use Skills to define how to analyze that data and generate reports.

Skills vs Subagents

The core distinction: Skills make Claude better at certain types of tasks; Subagents let Claude delegate tasks to independent "specialist workers."

Think of it this way: Skills are like training materials — they teach Claude how to do something. Subagents are like dedicated employees — they have their own workspace (context) and permissions (tools), complete tasks independently, and report back with results.

The two can be combined: for example, a code review sub-agent can load language-specific best practice Skills, achieving a "specialist + domain expertise" combination. According to Anthropic research, multi-agent systems (Claude Opus 4 as the orchestrator + Claude Sonnet 4 sub-agents) scored 90.2% higher than single-agent setups in internal evaluations.

Skills vs Slash Commands

If you've used Claude Code, you're familiar with slash commands like /commit and /review. The core distinction: Skills activate automatically based on context; slash commands require manual input to trigger.

Example: When you type /commit, Claude executes a predefined commit workflow — that's a slash command. When you say "help me write a weekly report," Claude automatically identifies and loads the weekly report generation Skill without any command input — that's Skills.

A simple way to remember: slash commands are keyboard shortcuts that you trigger manually; Skills are background knowledge that Claude uses at its own discretion.

Skills vs Plugins

Plugins are Claude Code's extension package mechanism. The core distinction: Skills are auto-activated capability extensions; Plugins are packaged and distributable complete workflow configurations.

The key insight: Plugins can contain Skills (in their skills/ directory) and represent a larger packaging unit. When you install a Plugin, its Skills are automatically activated, slash commands appear in autocomplete, and hooks are merged with your existing configuration.

In short: use Skills to extend Claude's capabilities; use Plugins to distribute standardized workflow configurations across your team.

Hands-On Tutorial

Option 1: Enable Built-in Skills

This is the easiest way to get started. Anthropic provides a set of practical document skills:

Steps to enable:

1. Log in to Claude.ai
2. Click your avatar in the top right and go to Settings
3. Find the Capabilities option
4. Enable the skills you need

Once enabled, test it right away: "Create an Excel spreadsheet for Q3 sales budget with monthly breakdowns and totals."

Note: Requires a Pro, Max, Team, or Enterprise plan, and the code execution feature must be enabled.

Option 2: Install Community Skills

If you use Claude Code, you can install community-contributed Skills via commands.

Install from the plugin marketplace:

# Add the official Skills repository
/plugin marketplace add anthropics/skills

# Install the document skills package
/plugin install document-skills@anthropic-agent-skills

# Install the example skills package
/plugin install example-skills@anthropic-agent-skills

Skills storage locations:

Option 3: Create a Custom Skill

This is where Skills truly shine — creating workflows tailored to your needs.

Step 1: Create the folder structure

mkdir -p ~/.claude/skills/weekly-report
cd ~/.claude/skills/weekly-report

A complete Skill folder might look like this:

weekly-report/
├── SKILL.md          # Core instructions (required)
├── template.md       # Report template (optional)
└── examples/         # Sample reports (optional)
    ├── good-example.md
    └── bad-example.md

Step 2: Write the SKILL.md

SKILL.md is the heart of the entire Skill. It consists of two parts: YAML frontmatter (metadata) and a Markdown body (detailed instructions).

Required metadata:

Optional metadata:

A complete weekly report generation Skill example:

---
name: weekly-report
description: 根据本周工作内容生成标准化的周报，包含进展、问题和下周计划
---

# 周报生成助手

## 使用场景
当用户需要生成周报、工作总结或进度汇报时，使用此技能。

## 输出格式
请按以下结构生成周报：

### 本周完成
- 列出已完成的主要工作项
- 每项包含简短说明和成果

### 进行中
- 列出正在进行的工作
- 标注当前进度和预期完成时间

### 遇到的问题
- 列出阻碍进展的问题
- 如果有，说明需要的支持

### 下周计划
- 列出下周的主要任务
- 按优先级排序

## 风格要求
- 使用简洁的表达
- 避免过于技术化的术语
- 突出成果和影响

## 示例

**输入**：这周完成了用户登录功能，修复了 3 个 bug，参加了产品评审。

**输出**：
### 本周完成
- 用户登录功能开发：完成前后端联调，支持邮箱和手机号登录
- Bug 修复：解决了 3 个高优先级问题，提升系统稳定性

### 进行中
- （无）

### 遇到的问题
- （无）

### 下周计划
- 开始用户注册功能开发
- 编写单元测试用例

Step 3: Test it

Test in Claude: "Help me generate this week's report. This week I completed the user login feature, fixed 3 bugs, and attended two product review meetings."

Using the Skill Creator

If you'd rather not write the SKILL.md from scratch, Claude has a built-in skill-creator skill that guides you interactively:

Help me create a skill for [your workflow]

Claude will walk you through a series of questions to clarify your requirements, then generate a draft SKILL.md.

Technical Principles

Skills as a Meta-Tool System

At their core, Skills are a meta-tool system — they don't execute code directly but inject specialized instructions into the conversation context, altering how Claude reasons.

When you trigger a Skill, two things happen:

1. Metadata message: A visible status indicator showing which Skill is being loaded
2. Skill prompt: The complete SKILL.md instructions are sent to Claude, hidden from the user

Discovery and Selection Mechanism

How does Claude know which Skill to invoke? The answer: it relies entirely on language understanding.

The name and description of all enabled Skills are formatted into a dynamic list written into the system prompt. When you send a message, Claude uses its native language understanding to match your intent and decide whether to invoke a given Skill.

This is why the description field is so critical — it's the sole basis for Claude's decision. There's no complex algorithmic routing; the decision happens entirely within Claude's reasoning process.

Best Practices

Through extensive real-world usage, the community has distilled four golden rules for creating Skills:

1. Stay Focused

A Skill should do one thing well. Multiple focused Skills are far more useful than one catch-all Skill — they're easier to maintain and easier to compose.

2. Write Clear Descriptions

The description field determines when Claude invokes your Skill, so be specific about the applicable scenarios. "Generate quarterly analysis reports from sales data" is a good description; "process data" is too vague.

3. Provide Examples

Including input/output examples in your SKILL.md significantly improves output consistency, especially for tasks with specific formatting requirements.

4. Start Simple

Begin with plain Markdown instructions, validate the results, and only then consider adding scripts. Increase complexity gradually.

Troubleshooting Common Issues

Security Considerations

Skills can execute code, so security matters:

• Trust the source: Only use Skills from trusted channels
• Review scripts: Inspect script code in Skills before installing
• Protect sensitive information: Never hardcode API keys or passwords in Skills
• Manage permissions: When used by a team, be mindful of the sharing scope of Skills

Current Limitations

As an emerging feature, Skills currently has some limitations:

Major Update (December 18, 2025): Anthropic officially released Agent Skills as an open standard. The specification and reference SDK are available at agentskills.io.

Companies/products that have adopted it:

• Microsoft: Integrated into VS Code and GitHub
• OpenAI: ChatGPT and Codex CLI use the same architecture
• Developer Tools: Cursor, Goose, Amp, OpenCode
• Partner Skills: Atlassian, Figma, Canva, Stripe, Notion, Zapier

Additionally, Anthropic, OpenAI, and Block co-founded the Agentic AI Foundation (hosted by the Linux Foundation), with Google, Microsoft, and AWS also joining. This means Skills is evolving from a single-vendor feature into an industry standard — Skills written for Claude Code can interoperate with OpenAI Codex CLI.

References:

• Anthropic makes agent Skills an open standard - SiliconANGLE
• OpenAI Adds 'Skills' Framework - WinBuzzer

Learning Resources

Official Resources

Community Picks

Recommended Reading

Looking Ahead

The emergence of Skills represents an important direction in AI tooling — enabling AI not just to execute tasks, but to learn and remember specific ways of working. Simon Willison predicted that Skills would trigger a "Cambrian Explosion" in the AI tool space, and that prediction is no exaggeration.

As more developers and teams build and share Skills, we can expect to see:

• Specialized Skills Marketplaces: Domain experts across industries packaging their knowledge into reusable Skills
• Deep Skills + MCP Integration: Forming complete end-to-end workflows
• Enterprise-Grade Skills Platforms: Team collaboration, version management, and access control

Now is a great time to get started. Here's what you can do right away: log in to Claude.ai and enable the document skills. This week, try installing a community Skill and creating your first simple Skill. In the long run, identifying repetitive work within your team and gradually building a dedicated skill library will be an effective way to boost productivity.

Further Reading

• A Complete Guide to Claude's System Architecture — Where Skills fit within the overall Claude system
• The Complete Guide to Claude Subagents — A deep dive into the Subagent mechanism
• My Claude Code Best Practices — Tips and tricks for everyday Claude Code usage