A 60-minute working session on building skills — for everyone who uses Claude.ai or Cowork.
60 minutes, 6 parts. Click any line to jump to that section.
Definition, why it matters, two kinds (task consistency vs workflow with MCP).
Folder structure, SKILL.md anatomy, the magic description line, optional folders.
Scopes, two paths to get a personal skill, two paths to share with your team.
Case study: /salesforce-churn-check — architecture, snippets, output.
Build → smoke test → peer review → iterate → distribute.
internal org skills already live, thinking model, take-home.
A folder of instructions Claude reads when it's relevant. Nothing more.
A folder you upload to Claude. It teaches Claude how to do one specific task — your team's report format, your brand voice, your weekly process — the way you want it done. Claude reads the recipe only when it's relevant.
The official definition: "A skill is a set of instructions — packaged as a simple folder — that teaches Claude how to handle specific tasks or workflows."
— Anthropic, The Complete Guide to Building Skills for Claude
Same task — checking the product idea board in YouTrack every Monday. Same data, same MCP. Different ask.
You, every Monday:
"Claude, use the YouTrack MCP to pull from our Product Ideas board (project PRD). Show me ideas in New status waiting to be reviewed, ideas rejected in the last 7 days, and ones accepted this week. Three numbers with one example each."
Re-typed every week.
Format drifts every time.
You, every Monday:
"Claude, what's on the idea board this week?"
Claude reads the skill, queries YouTrack via MCP, returns the same three numbers in the same shape.
Same every Monday.
Almost every skill is one of these. Pick whichever matches what you actually do at work.
Same task. Same shape every time.
No external data needed. The skill teaches Claude your format, tone, conventions, brand voice — so the output is the same whether you ask on Monday or Friday, and whoever asks.
Examples: /brand-assets, /reprompt
Connect → process → output.
The skill calls an MCP to pull live data (Salesforce, YouTrack, Notion), applies your team's process, and returns it in your shape. MCP at the start, the end, or both.
Examples: /salesforce-forecast, /salesforce-churn-check, the YouTrack idea-board skill
It's just a folder with one important file. Let's open it up.
The folder name becomes the skill name. Inside, only one file is required: SKILL.md. Everything else is optional helpers — most skills don't need them.
kebab-case (lowercase, hyphens — no spaces, no capitals). The file inside must be spelled exactly SKILL.md — capitalised, with a dot.
SKILL.md how to use them. "Before drafting, consult references/style-guide.md" or "Run scripts/validate.py to check the data". Without that pointer, the files just sit there — Claude won't reach for them on its own.
Between two --- markers. Tells Claude the skill's name and when to use it. This is the only part Claude always sees.
Everything below the label. This is a prompt — the same kind you'd write in chat, just polished. Clear task, specific format, examples, constraints. Claude reads it only when the label says it's relevant.
---
name: weekly-status-update
description: Writes my weekly status update. Use when I ask for a
"weekly update", "status report", or "Friday recap". Output is
~200 words in three sections (wins, blockers, next week).
---
# Weekly Status Update
Write the update in three sections.../reprompt skill to turn rough notes into a polished one — then paste the result in as your instructions. You already know how to write skills; you just didn't know it.
Each layer only loads if the layer above said it was relevant — which is why you can have many skills installed without slowing anything down.
The skill's name and a one-line description of when to use it.
The full how-to. Format, steps, examples, tone.
Scripts Claude can run, long references, sample outputs, templates.
Layer 1 is the only line Claude always has loaded. Get it right and your skill triggers reliably. Get it wrong and Claude never picks it up — even if the rest of the skill is perfect.
"Helps with reports."
No trigger words. No specifics. Claude won't know when to use it.
"Writes my weekly status update in three sections. Use when I say 'weekly update', 'status report', or 'Friday recap'."
What + when + actual words I'd say.
When SKILL.md alone isn't enough. Add these only when you need them — but knowing what each unlocks helps you spot the right moment.
Python or bash scripts the skill executes. Use when the task needs real determinism — validation, data processing, generating files from templates.
"Code is deterministic; language interpretation isn't." — Anthropic's skills guide
API references, style guides, full domain knowledge. Keep SKILL.md focused on the core flow — point to references/ for material that only loads when Claude reaches for it.
Example: references/api-patterns.md for rate limits, pagination, error codes.
Templates, logos, fonts, icons. Used in what Claude produces — not in what Claude reads. Add them when output needs brand polish.
Real example: /brand-assets Bundles the company logos and colors here.
Install a skill in your account — then put yours in front of others.
Skills work everywhere Claude does — but you choose who can see them. Pick the scope that matches who needs the skill.
Skills Anthropic ships with Claude itself — /skill-creator, /code-review, /debug, others. You don't manage these.
You upload it to your account. Active in every chat and every Cowork session — but only yours. Where most people start.
Your personal skill, shared via Customize → Skills → Share. Send to specific people by name/email, or publish to your org's directory. Team/Enterprise plans only.
The Team or Enterprise owner provisions a skill from Organization settings → Skills. Appears for every member, view-only.
Two paths to your first personal skill. Pick whichever matches where you're starting from.
You don't have a folder yet — start from a conversation.
/skill-creator — Anthropic's built-in skill. Walks you through name, description, and instructions. Outputs a ready-to-use SKILL.md./reprompt — describe what you want as a task. The polished prompt it returns is your SKILL.md body — wrap it with frontmatter, done.Fastest path for first-timers. No file handling.
Three sources, one install flow.
github.com/anthropics/skills and grab the folder..zip or share it via Claude.Install: Customize → Skills → Upload .zip → Toggle on.
Both end up in front of colleagues — different mechanism, different control.
From inside Customize → Skills → Share:
Recipients can enable and use the skill, but can't edit it.
From Organization settings → Skills:
Best for shared standards your whole team should follow.
/salesforce-churn-check — architecture, snippets, output, and why each folder earns its place.
Surface B2B accounts whose Flash Test cadence has collapsed vs their own historical baseline — a churn signal the existing Salesforce dashboards can't catch.
A daily-tester quiet for 7 days = alarming. A monthly-tester quiet for 7 days = normal. Salesforce can't tell the two apart.
/brand-assets, ping owners on Slack, email it to a customer — chain any connector your team has.The CSM gets to act, not query. Salesforce expertise stops being a bottleneck.
All three optional folders show up in a real Type-2 skill — each plays a distinct role.
holidays package)references/ holds rules too dense to inline (gotchas like Not_Billable__c = false meaning is billable). scripts/ does the math — code is deterministic; language interpretation isn't.
The frontmatter carries the trigger phrases. The body points Claude to references/ and scripts/ exactly when needed.
---
name: salesforce-churn-check
description: "Find B2B accounts whose paid Flash Test cadence has
collapsed vs their OWN historical baseline... Triggers on:
'who has gone quiet', 'which accounts stopped testing',
'churn signals', 'silent customers', 'accounts at risk',
'drop in testing', 'inactive accounts', 'churn check',
'where should CSM look'."
compatibility: "Requires Python 3 with the holidays package
and the Salesforce MCP."
---
# Salesforce pulse check
## Critical: read references first
Before constructing any SOQL, read `references/filter-rules.md`
for the canonical Filter A and the Rule-0 aggregate cap.
### Step 1 — Baseline counts per account: days 30–90 ago (60-day window)
### Step 2 — Recent counts per account: last 30 days ← the comparison vs Step 1
### Step 3 — Same baseline window, 52 weeks back (year-over-year check)
### Step 4 — Same recent window, 52 weeks back (year-over-year check)
### Step 5 — Join Steps 1–4 by AccountId, write /tmp/churn.csv
### Step 6 — Run scripts/find_quiet_accounts.py — workdays, ratios, severity
### Step 7 — Present the ranked watchlist with owners to ping
Output is a markdown report. Severity bands, year-over-year seasonality flag, and a per-owner queue so each CSM gets one ping with their full list.
# Quiet accounts report — 2026-05-25
## Flagged accounts (12)
| Account | Country | Owner | Baseline/wk | Recent/wk | Ratio | LY ratio | Severity |
|--------------------|---------|--------------|-------------|-----------|-------|----------|--------------|
| Henley Cars Ltd | UK | Alexander S. | 28.1 | 1.3 | 5% | — | 🔴 critical |
| ACME Motors | DE | Bram H. | 23.4 | 0.5 | 2% | — | 🔴 critical |
| Autohaus Lang | AT | Alberto R. | 19.0 | 1.5 | 8% | — | 🔴 critical |
| Alpine Service Co | CH | Alexander S. | 22.8 | 4.1 | 18% | 19% | 🟠 (seasonal) |
| ... | | | | | | | |
## Owners to ping
- Alexander S. — 2 critical, 1 seasonal (watch only)
- Bram H. — 1 critical
- Alberto R. — 1 critical
references/ enforces the canonical filter, scripts/ does the per-account math, SKILL.md orchestrates. The CSM didn't need to know any of it — they just asked the question.
Neither folder is decorative. Each one absorbs work that would otherwise be in SKILL.md — making the skill faster, cheaper, and more reliable.
Tells Claude what your domain words mean.
Not_Billable__c = false means is billable)Without it: Claude guesses field names. With it: Claude follows the canonical rules.
Code beats prompting for boring math.
holidays package)Faster, cheaper, exact. Claude is overkill for math — and an LLM can't import Python's holiday package.
Build → smoke test → peer review → iterate → distribute.
Every skill that lands in production runs this loop. Skip a phase and you'll find out the hard way — by shipping something that triggers wrong or embarrasses you in a team chat.
Write SKILL.md. Description + instructions in plain English.
Trigger it yourself 3–5 times. Check output. Check speed.
Have another LLM (or reviewer prompt) critique what you built.
Fix what came back. Re-test. Repeat until it feels solid.
Share via Claude, zip the folder, or push as an org skill.
Trigger your skill 3–5 times with realistic inputs. For each run, look at these four dimensions before showing it to anyone else.
Does Claude actually pick the skill up when you ask? If not, the description's trigger phrases need work.
How long does it take? Acceptable for the workflow? Can you trim the body to run faster without compromising output quality?
Is it readable? Trim useless info that's bloating the response. Headers, bullets, length — all easy to tighten.
Is the data granular enough? Precise where it needs to be? Or vague, hallucinated, missing the specifics that matter?
If anything feels off — straight back to Phase 1 (build) and fix it. No skill ships from smoke test directly.
The same model with the same blind spots can't catch its own errors. Two patterns to outsource the review — pick one, or run both for higher catch rate.
Reviewer agent grades the same four checks.
If you have ground truth, diff against it.
Only works when you have a known-good example to compare against.
Each of the four checks maps to a kind of fix. Expect 2–3 cycles before a skill feels solid. Most fixes live in the description or instructions — not in code.
Under: add more trigger phrases — words you'd actually say.
Over: narrow the description, add "Do NOT use for…" to scope it.
Output too verbose, hard to scan, or wrong shape. Trim the instructions — fewer rules, more examples of the right output.
Output vague, hallucinated, or low granularity. Tighten requirements in the body. Add a sample of "good" so Claude has a target.
Skill takes too long. Cut anything not strictly needed. Move long reference material to references/ so it loads only when needed.
Once your skill passes review, pick the distribution that matches the audience.
Open your skill in Customize → Skills → Share. Send to specific people by name/email, or publish to your org's directory.
Use when: Team/Enterprise plan with sharing enabled.
Compress the folder. Drop the .zip in Slack, email, or DM. They upload via Customize → Skills.
Use when: no Team plan, or sharing isn't enabled yet.
Hand the .zip to your Team or Enterprise owner. They provision it from Organization settings → Skills — everyone gets it, view-only.
Use when: it's a shared standard for the team.
Use what's already live. Then build your own.
Four org-provisioned skills — already available to everyone in the workspace. Salesforce skills land shortly.
/reprompt AvailableScores every substantive prompt against the Prompt Standard. Strong prompts pass through; weak ones get rewritten inline with a coaching note.
/brand-assets AvailableBundles the company logos and brand colors. Auto-fires when Claude produces a report, deck, presentation, dashboard, or branded artifact.
/salesforce-forecast Coming soonForecasts daily Flash Test volume per account or country with national-holiday awareness. Separates expected dips from churn signals.
/salesforce-churn-check Coming soonFinds B2B accounts whose Flash Test cadence has collapsed against their own baseline. Returns a ranked CSM watchlist.
Pick a task you repeat. Walk these in order — your SKILL.md falls out the other end.
The prompt you've sent more than twice is your skill candidate. Vague isn't enough — you need a task you do regularly.
Does it need live data from an MCP (Salesforce, YouTrack, Notion), or is it just task consistency (brand voice, weekly format)? That's the shape.
The actual phrases you'd say — "weekly update", "idea board", "draft an email". Three to five variations. That's the description.
Length, sections, tone, hard rules. Write a sample of what "good" looks like — that goes in the body.
/skill-creator or /reprompt to turn these four answers into a SKILL.md.
A skill is a folder with one file. SKILL.md is plain English instructions Claude reads when they're relevant — nothing more.
The description is the magic. Write it using the actual trigger phrases you'd say. That single line decides whether your skill ever runs.
A skill's body is a polished prompt. Use /reprompt from Workshop #2 to turn rough notes into one — then drop it in.
Now go teach Claude how you work.
#ai-office-hours on Slack