A Complete Guide to Claude Skill: From Zero to Your First Custom AI Skill

Optimize your AI workflow, standardize team output, and turn prompts into reusable skills

Introduction: Why You Need to Master Claude Skill

Have you ever faced these frustrations?

• Repeating your team’s coding guidelines every time you ask Claude to write code.
• Losing a perfectly tuned prompt when switching projects.
• Inconsistent AI output across your team because everyone uses different prompts.

Claude Skill is the solution. It lets you permanently capture your AI knowledge—teach once, benefit forever. In this guide, you’ll go from zero to building your first custom, shareable Skill.

1. What Exactly Is Claude Skill?

1.1 The Simplest Analogy: AI’s “Onboarding Manual + Toolkit”

Think of Claude as a brilliant new intern.

• A normal prompt = verbal instructions every single task.
• An Agent Skill = a full, written Standard Operating Procedure (SOP).

It includes:

• 📋 Onboarding Manual (SKILL.md) – role, workflow, rules, and constraints.
• 🧰 Toolbox (scripts/) – reusable scripts for specialized jobs.
• 📚 Reference Library (references/) – specs, templates, APIs, and docs.

1.2 Technical Definition

A Skill is a standardized folder that contains a complete set of instructions for Claude to perform a specific task.

Its core value:

• Teach once, use forever – no repeated prompting.
• Cross-environment compatible – works on Claude.ai, Claude Code, and API.
• Composable – multiple Skills can work together.

1.3 Skill vs Prompt vs MCP

Many beginners mix these up. Here’s a clear breakdown:

💡 MCP + Skill = Superpower MCP gives Claude tools (e.g., database access). Skill teaches it your team’s rules for querying, reporting, and handling errors.

2. Three Core Design Principles of Skill

Master these, and you’ll design professional, reliable Skills.

2.1 Progressive Disclosure

The most important architectural pattern. Instead of flooding Claude with all information at once, it loads in three layers:

Formula: Total tokens ≈ 100 (metadata) + 5000 (body) + on-demand resources.

2.2 Composability

Skills work together. Your Skill should not assume it’s the only one active.

• ✅ frontend-design + docx-creator
• ✅ sentry-code-review + github-workflow
• ✅ skill-creator + your-custom-skill

2.3 Portability

The same Skill behaves consistently everywhere:

• Claude.ai (web): Enable in Settings → Capabilities
• Claude Code (desktop): Place in ~/.claude/skills/
• Claude API: Specify skills in your request

3. Standard Skill Directory Structure

A real-world Skill looks like this:

your-skill-name/          # kebab-case, lowercase only
├── SKILL.md              # REQUIRED – main instruction file
├── scripts/              # OPTIONAL – executable code (Python/Bash)
├── references/           # OPTIONAL – docs loaded on demand
└── assets/               # OPTIONAL – templates, static files

⚠️ Critical Naming Rules

4. Build Your First Skill – Step by Step

We’ll create a Meeting Minutes Assistant as an example.

4.1 Step 1: Define the Skill (30–60 min)

Clarify your goal:

• Use case: Convert raw meeting transcripts into structured minutes.
• Types: Weekly sync, project retro, client call.
• Trigger phrases: “Summarize meeting”, “Create minutes”, “Organize discussion notes”.

4.2 Step 2: Initialize the Folder (5 min)

Option A: Manual

mkdir -p ~/.claude/skills/meeting-minutes
cd ~/.claude/skills/meeting-minutes
mkdir -p references

Option B: Use official skill-creator (recommended)

git clone https://github.com/anthropics/skills
cd skills
python scripts/init_skill.py meeting-minutes --path ~/.claude/skills/

4.3 Step 3: Write SKILL.md (Core File)

4.3.1 YAML Frontmatter

name: meeting-minutes
description: General office meeting minutes assistant. Supports weekly sync, project retro, and client communication. Automatically detects meeting type, loads templates, extracts action items, and outputs structured notes. Use when user says "整理会议记录", "生成会议纪要", "summarize meeting", or "create minutes".

Description Best Practices:

• Must explain what it does AND when to use it.
• Under 1024 characters.
• Include clear trigger phrases.

4.3.2 Markdown Body

# Meeting Minutes Assistant
Follow this workflow strictly:
## 1. Identify Meeting Type
Detect from keywords:
- Weekly sync: “weekly”, “this week”, “next week”, “report”
- Project retro: “retro”, “summary”, “lesson”, “improve”
- Client call: “client”, “customer”, “requirement”, “feedback”
## 2. Load Template from references/
- Weekly → weekly-rule.md
- Retro → retro-rule.md
- Client → client-rule.md
## 3. Extract Key Information
- Action items (owner + deadline)
- Unresolved issues
- Key decisions
- Important deadlines
## 4. Output Structure
### 📅 Meeting Info
- **Topic**:
- **Time**:
- **Attendees**:
### 📋 Core Content
[Structured based on meeting type]
### ✅ Action Items
| Task | Owner | Deadline |
|------|-------|----------|
| | | |
### ⚠️ Unresolved Issues
-

4.4 Step 4: Add Reference Templates (Optional)

Place templates inside references/:

• weekly-rule.md
• retro-rule.md
• client-rule.md

4.5 Step 5: Test Your Skill

1. Restart Claude Code.

2. List loaded skills:

   /skills

3. Test with a real prompt:

   Create weekly meeting minutes from this text:
   John: I finished the user module and sent it to QA.
   Jane: I’ll finish API docs by Friday.
   Mike: The staging bug needs ops help.

4. Claude should automatically suggest using your Skill.

4.6 Step 6: Package & Share

python scripts/package_skill.py ~/.claude/skills/meeting-minutes ./dist

This outputs a shareable .my-skill file (zip archive).

5. Advanced Tips & Best Practices

5.1 Metadata = Skill Trigger

The description field directly controls whether your Skill activates.

Good:

description: Creates sprint plans from Linear data. Use when user says "plan sprint" or "create weekly tasks".

Bad:

description: Creates sprint plans. # missing trigger
description: Use for sprints. # missing purpose

5.2 Use scripts/ to Save Tokens

Scripts run without being read into context.

• Great for PDF processing, file conversion, API calls.
• Remember permissions: chmod +x scripts/*.py

5.3 Improve Security with allowed-tools

Restrict which tools Claude can use:

name: safe-reader
description: Read files safely without edits.
allowed-tools: Read, Grep, Glob

5.4 Use Skills in Subagents

name: code-reviewer
description: Senior code reviewer
skills: pr-review, security-check

5.5 Debugging

• Run in debug mode: claude --debug
• Check YAML syntax
• Clear cache: rm -rf ~/.claude/plugins/cache

6. Three Classic Skill Use Cases

6.1 Document & Asset Creation

• Example: frontend-design
• Style guides + templates + quality checks

6.2 Workflow Automation

• Example: skill-creator
• Step-by-step guided workflows

6.3 MCP Enhancement

• Example: sentry-code-review
• Orchestrate external tool sequences
• Add error handling & domain knowledge

7. How to Measure a Successful Skill

Quantitative

• ✅ Triggers correctly on 90%+ of relevant queries
• ✅ Fewer tool calls vs. plain prompts
• ✅ 0 API failures

Qualitative

• ✅ User doesn’t need to correct Claude
• ✅ Consistent cross-session output
• ✅ Works seamlessly in a team

8. FAQ

Q1: Relationship between Skill and Command?

A: Commands have been merged into the Skill system.

• Old .claude/commands/ still work.
• New features should use Skills for full power: scripts, references, auto-trigger, subagents.

Q2: Do Skills auto-trigger?

A: Yes. Claude scans metadata and loads the Skill when intent matches.

Q3: Can I use multiple Skills at once?

A: Absolutely. Skills are composable.

Q4: Do I need to code?

• Using Skills: No coding needed.
• Basic Skills: Only Markdown.
• Advanced Skills: Python/Bash helpful for scripts/.

Q5: Where to learn more?

• DeepLearning.AI: Agent Skills with Anthropic
• Official: The Complete Guide to Building Skills for Claude
• GitHub: anthropics/skills

9. Conclusion: From Prompt Engineering to Skill Engineering

Claude Agent Skills mark the shift from one-off prompt engineering to sustainable, shareable skill engineering.

You’re not just writing prompts—you’re building digital assets that:

• Save tokens
• Standardize team behavior
• Scale across projects and environments

Start today. Spend 15 minutes building your first Skill. Once you experience “teach once, use forever”, you’ll never go back.