Building Your First Skill (step-by-step)

TL;DR

A Skill = folder with SKILL.md (instructions) + optional scripts. The description is what matters most — it’s what makes Claude activate the skill on its own. Here you’ll create yours in 10 minutes.

Captura de tela

Settings → Features → Skills panel in Claude.ai

claude.ai/settings/skills

1

Features

2

Create Skill

3

Skill list

4

Activation toggle

Abrir ↗

1. 1 Features — side tab in Settings
2. 2 Create Skill — create a new skill via wizard or .zip upload
3. 3 Skill list — your skills + pre-built (xlsx, docx, pptx, pdf)
4. 4 Activation toggle — enables/disables without deleting

Before starting — the fundamental principle

Claude is already very smart. Your skill should add only what it doesn’t know.

This comes straight from Anthropic’s official docs. Don’t write “PDF is a file format that contains text and images…” — it knows.

Write only:

• Conventions specific to your company
• Business rules
• Patterns you want reinforced
• Specific workflows
• Internal schemas / names / codes

Step 1 · Decide what the skill does

Don’t start with the skill. Start by doing the task manually with Claude, without a skill.

Notice:

• What did you have to explain every time?
• Which company conventions did Claude not know?
• What was missing from the result?

That’s the content of the skill. It’s not “everything about sales analysis” — it’s what was missing when you did it without a skill.

Step 2 · Name it well

Anthropic’s official rule:

• Lowercase, hyphens, no special characters
• Maximum 64 characters
• No reserved words (anthropic, claude)
• Use the gerund or process name, not a generic noun

✓ Good	✗ Bad
analyzing-sales-funnel	funnel
reviewing-br-contracts	contracts
standardizing-cs-emails	emails
auditing-br-taxes	tax

Step 3 · Write the description (what matters most)

The description is what makes Claude pick your skill from among 100 others. Get this wrong and the skill never activates.

Official rules

• Always third person (not “I help you with…”; yes “Analyzes sales funnel…”)
• Include what it does + when to use
• Specific terms that trigger activation
• Maximum 1024 characters (but shorter is better)

Real examples

❌ Bad:

description: Helps with sales

✓ Good:

description: Analyzes sales funnel spreadsheets (HubSpot, Pipedrive, RD Station exports). Calculates CAC, LTV, conversion per stage, average ticket, sales cycle. Identifies bottlenecks and compares reps. Use when the user sends a CRM export, lead spreadsheet, or asks for a sales diagnosis.

Step 4 · Structure the SKILL.md

Minimum structure that works:

---
name: analyzing-sales-funnel
description: [full description as above]
---

# Sales Funnel Analysis

## When to use
- Spreadsheet with funnel stage columns
- CRM export (HubSpot, Pipedrive, RD)
- Question about conversion, CAC, LTV, or sales productivity

## Workflow
1. Identify the funnel structure (stages, order, volumes)
2. Calculate conversion between each stage
3. Identify bottlenecks (drop > 60% between adjacent stages)
4. Compare reps (only if there's a rep-owner column)
5. Calculate KPIs: overall conversion, average ticket, sales cycle

## Conventions for this company
- "MQL" = Marketing Qualified Lead (comes from inbound)
- "SQL" = Sales Qualified Lead (passed through the SDR)
- Reps: Carla, Diego, Bia, Luan (the current 4)
- Default period: last 90 days
- Exclude leads with status "duplicate" or "test"

## Output format
- Executive summary (5 bullets, with R$ involved)
- Funnel table
- Top 3 bottlenecks with action for the next 7 days
- Positive outlier + negative outlier among reps

## Anti-patterns
- DO NOT include CAC if no cost data exists
- DO NOT infer reason for loss — ask the user
- DO NOT compare with market benchmark without explicit warning

See what’s happening here:

• Company conventions are inside the skill — Claude wouldn’t have known on its own
• Numbered workflow eliminates “forgetting a step”
• Anti-patterns prevent common mistakes that happened before

Step 5 · Install the skill

In Claude.ai (easiest)

1. Go to Settings → Features → Skills
2. Enable Code execution (required for custom Skills)
3. Save your skill as a .zip:
   • Create a folder with the skill name
   • Put SKILL.md inside
   • Compress as zip
4. Click Upload Skill and send the zip
5. Done — the skill appears in the list

In Claude Code (filesystem)

mkdir -p ~/.claude/skills/analyzing-sales-funnel
cd ~/.claude/skills/analyzing-sales-funnel
# create SKILL.md here

Done — Claude Code discovers it automatically.

For the team (sharing)

Put it in .claude/skills/ at the project root and commit to Git. Every dev who clones the repo gets the skill.

Step 6 · Test

Don’t trust intuition alone. Test 3 real scenarios:

1. Typical request — “analyze this sales spreadsheet” → does the skill activate, follow the workflow?
2. Biased request — “calculate only the CAC” → does the skill activate partially, doing only the request?
3. Out-of-scope request — “write an email to a customer” → does the skill NOT activate, correctly?

If the skill activates when it shouldn’t, the description is too vague. If the skill doesn’t activate when it should, add key terms to the description.

Common mistakes (that will cost you time)

Description in first person

“I can analyze spreadsheets…”

It has to be third person. Otherwise, Claude gets confused about who “I” is in context.

SKILL.md too long

800 lines of explanation

Limit: 500 lines in the body. Above that, break it into separate files (FUNNEL.md, KPIS.md) and reference them from SKILL.md.

”Voodoo constants”

TIMEOUT = 47

If you have a magic number in a script, comment why. Otherwise Claude will want to change it and break things.

Not testing across the 3 models

The skill works on Opus but fails on Haiku? Watch out — description is too subtle. Haiku needs a more explicit hint.

Skill in production — checklist

Before sharing with the team:

• Description in 3rd person, with key terms
• Name in gerund or process form
• SKILL.md < 500 lines
• Company conventions documented
• Numbered workflow
• Anti-patterns listed
• Tested on typical, partial, and out-of-scope requests
• Tested on Haiku, Sonnet, and Opus
• No secrets or sensitive data inside

Next step

See how to connect Claude to your systems — Skills + Connectors = complete automation.

Or explore the prompt library for inspiration on skills your company can create.