Reading · AI For Developers

If you’ve been using Claude for a while, you’ve probably noticed the pattern: you explain the same context, the same formatting rules, the same workflow — over and over again, every new conversation.

Skills fix that.

They’re one of the most underused features in Claude right now, and once you start using them, you’ll wonder how you worked without them. In this guide, I’ll walk you through everything: what skills are, how to write one from scratch, how to install and share them, and how to actually make them trigger reliably. Whether you use Claude.ai, Claude Code, or the API, this covers all of it.

Let’s get into it.

Skills are folders of instructions, scripts, and resources that extend Claude’s capabilities for specialized tasks. Think of them as reusable “expertise packages” — instead of re-explaining a workflow every time, you encode it once as a skill, and Claude applies it automatically whenever it’s relevant.

A skill can be as simple as a few lines of brand guidelines or as complex as a multi-file package with executable Python scripts, templates, and reference documents.

Skills work across Claude.ai, Claude Code, and the API.

Plan: Free, Pro, Max, Team, or Enterprise
Code Execution: Must be enabled in Settings → Capabilities
Enterprise plans: Organization owners must enable both Code execution and Skills in Admin settings before members can use them
Team plans: Skills are enabled by default at the organization level

Every skill is a folder containing at minimum a SKILL.md file. Here’s what the structure looks like:

my-skill/
├── SKILL.md            ← required (instructions + metadata)
├── scripts/            ← optional: executable code
│   └── process.py
├── references/         ← optional: docs loaded as needed
│   └── style-guide.md
└── assets/             ← optional: templates, fonts, icons
    └── logo.png

This is the core of every skill. It has two parts: YAML frontmatter (metadata) and Markdown body (instructions).

---
name: my-skill-name
description: >
  A clear description of what this skill does and when to use it.
  Include trigger phrases and contexts so Claude knows when to activate it.
---
# My Skill Name
## Overview
What this skill does and why it exists.
## Instructions
Step-by-step guidance for Claude to follow.
## Examples
Show Claude what good output looks like.

name — identifier for the skill (use lowercase-kebab-case)
description — when to trigger and what it does — this is the primary trigger mechanism

dependencies — software packages required by the skill
license — license information or path to license file

The description field in your frontmatter is the single most important part of your skill. Claude reads every skill’s name and description to decide which skill to load for a given request. If the description doesn’t match, the skill won’t trigger.

Tips for good descriptions:

Be specific about what the skill does AND when to use it
Include trigger phrases and contexts
Be a little “pushy” — Claude tends to under-trigger skills, so err on the side of over-describing when it should be used
Mention related keywords, file types, and use cases

Bad description:

description: Format data nicely.

Good description:

description: >
  Apply Acme Corp brand guidelines to all presentations, documents,
  and marketing materials. Use this skill whenever the user mentions
  brand colors, typography, company style guide, Acme branding,
  visual identity, or asks for materials that should look “on-brand.”
  Also use when creating any client-facing deliverable.

The body of SKILL.md is where you tell Claude how to do the work. Follow these principles:

1. Explain the “why,” not just the “what”

Claude is smart. If you explain why something matters, it can generalize better than if you give rigid rules.

<!-- Instead of this -->
ALWAYS use 14pt font for body text.
<!-- Do this -->
Use 14pt font for body text — this ensures readability
when printed or projected, which is common for these deliverables.

2. Use imperative form

Write instructions as direct commands.

## Steps
1. Read the uploaded file
2. Extract all table data
3. Reformat using the template in assets/template.xlsx
4. Save the output as a new file

3. Include examples

Examples are one of the most effective ways to steer Claude’s behavior.

## Commit Message Format
**Example 1:**
Input: Added user authentication with JWT tokens
Output: feat(auth): implement JWT-based authentication
**Example 2:**
Input: Fixed crash when clicking submit with empty form
Output: fix(forms): handle empty form submission gracefully

4. Define output formats explicitly

## Report Structure
ALWAYS use this template:
# [Title]
## Executive Summary
## Key Findings
## Recommendations
## Appendix

Skills use a three-level loading system to be efficient:

Metadata (name + description) — Always loaded (~100 words). Claude uses this to decide if the skill is relevant.
SKILL.md body — Loaded when the skill triggers. Keep under ~500 lines.
Bundled resources (scripts, references, assets) — Loaded on demand. Can be unlimited size.

If your skill is getting long, move detailed reference material into references/ files and point to them from SKILL.md:

## Supported Platforms
For platform-specific instructions, read the appropriate reference file:
- AWS: `references/aws.md`
- GCP: `references/gcp.md`
- Azure: `references/azure.md`

For tasks that benefit from deterministic code (data processing, file conversion, chart generation), bundle scripts in a scripts/ directory.

my-skill/
├── SKILL.md
└── scripts/
    ├── generate_chart.py
    └── process_data.py

In your SKILL.md, reference them:

## Chart Generation
Run `scripts/generate_chart.py` with the input CSV to produce
the visualization. The script accepts:
- `--input`: path to the CSV file
- `--output`: path for the output PNG
- `--style`: one of “minimal”, “corporate”, “colorful”

Note on dependencies: Claude can install packages from PyPI (pip) and npm at runtime in Claude.ai and Claude Code. For API usage, all dependencies must be pre-installed in the container. List them in your frontmatter:

dependencies:
  - python-pptx
  - pandas
  - matplotlib

For large bodies of knowledge that Claude should consult selectively:

my-skill/
├── SKILL.md
└── references/
    ├── api-v1.md
    ├── api-v2.md
    └── migration-guide.md

For templates, images, fonts, or other files used in output:

my-skill/
├── SKILL.md
└── assets/
    ├── report-template.docx
    ├── company-logo.png
    └── fonts/
        └── BrandFont.ttf

---
name: brand-guidelines
description: >
  Apply Acme Corp brand guidelines to presentations, documents,
  and marketing materials. Use whenever the user mentions brand
  colors, typography, company style, or creates client-facing content.
---
# Acme Corp Brand Guidelines
## Colors
- Primary: `#1a2b3c` (Navy)
- Accent: `#e74c3c` (Red)
- Background: `#f8f9fa` (Light Gray)
- Text: `#2c3e50` (Dark Gray)
## Typography
- Headings: Montserrat Bold
- Body: Open Sans Regular
- Code: JetBrains Mono
## Voice & Tone
- Professional but approachable
- Active voice preferred
- Short sentences for clarity

---
name: code-review
description: >
  Review code for quality, security, and best practices. Use when
  the user asks for a code review, wants feedback on their code,
  asks “is this code good?”, or submits a pull request for review.
---
# Code Review Skill
## Review Checklist
When reviewing code, evaluate each of these areas:
1. **Correctness**: Does the code do what it claims?
2. **Security**: Are there injection risks, exposed secrets,
   or missing input validation?
3. **Performance**: Any N+1 queries, unnecessary loops,
   or missing caching opportunities?
4. **Readability**: Clear naming, appropriate comments,
   consistent formatting?
5. **Testing**: Are edge cases covered? Are tests meaningful?
## Output Format
Structure every review as:
### Summary
One paragraph overall assessment.
### Issues Found
List each issue with severity (critical / warning / suggestion),
file and line reference, and a recommended fix.
### What’s Done Well
Highlight 2-3 things the code does right — reviews shouldn’t
only be negative.

data-dashboard/
├── SKILL.md
├── scripts/
│   └── build_dashboard.py
└── assets/
    └── dashboard_template.html

---
name: data-dashboard
description: >
  Create interactive data dashboards from CSV or Excel files.
  Use when the user wants to visualize data, create a dashboard,
  make charts from a spreadsheet, or says “show me this data.”
dependencies:
  - pandas
  - plotly
---
# Data Dashboard Skill
## Workflow
1. Read the user’s data file (CSV, XLSX, or TSV)
2. Analyze columns and data types automatically
3. Run `scripts/build_dashboard.py` to generate the dashboard
4. Output an interactive HTML file
## Script Usage
```bash
python scripts/build_dashboard.py \
  --input data.csv \
  --output dashboard.html \
  --title “Q3 Sales Dashboard”

Time series data → Line chart
Categorical comparisons → Bar chart
Part-to-whole → Pie or donut chart
Correlations → Scatter plot
Distributions → Histogram

Go to Settings → Customize → Skills (or the Customize panel)
Click Upload Skill
Select your .zip or .skill file
Claude reads your SKILL.md and displays the skill details
Toggle the skill on to activate it

Packaging your skill for upload:

Put your skill folder inside a ZIP file
The ZIP should contain the skill folder as its root (not nested inside another folder)
The folder name should match your skill’s name field

my-skill.zip
└── my-skill/
    ├── SKILL.md
    └── scripts/
        └── process.py

Place skills in one of these locations:

Project-level (shared with your repo):

your-project/
└── .claude/
    └── skills/
        └── my-skill/
            └── SKILL.md

User-level (available across all projects):

~/.claude/skills/my-skill/SKILL.md

Claude Code discovers and loads skills automatically. You can also invoke them directly with /my-skill-name.

Upload skills using the Skills API:

curl -X POST “https://api.anthropic.com/v1/skills” \
  -H “x-api-key: $ANTHROPIC_API_KEY” \
  -H “anthropic-version: 2023-06-01” \
  -H “anthropic-beta: skills-2025-10-02” \
  -F “display_title=My Skill Name” \
  -F “files[]=@my-skill/SKILL.md;filename=my-skill/SKILL.md”

In Customize → Skills, open a skill you created. You can share it with:

Specific people: Enter names or emails. The skill appears in their skills list (grayed out until they enable it).
Entire organization: Published to your org’s directory where anyone can find and install it.

Shared skills are view-only — recipients can enable and use them but can’t edit them. Updates you make are automatically pushed to recipients.

Package your skill folder as a .zip file and share it directly. Recipients upload it through their own Skills settings.

After uploading your skill:

Open a new chat
Ask Claude something that should trigger your skill — try both explicit mentions (”Use my brand guidelines skill to...”) and implicit triggers (”Create a client-facing presentation”)
Check that the output follows your instructions
Test edge cases and unexpected inputs

Claude has a built-in skill for creating and improving skills. You can use it by asking Claude directly:

“I want to create a skill that does X. Can you help me build it?”

The skill creator walks you through:

Defining what the skill should do
Writing a draft SKILL.md
Creating test cases
Running test prompts
Evaluating results
Iterating until you’re satisfied
Packaging the final skill

Skill doesn’t trigger:

Broaden your description field — add more trigger phrases and contexts
Be more explicit in your prompt: “Use my [skill-name] skill to...”
Ensure the skill is toggled on in Customize → Skills
Verify code execution is enabled

Inconsistent results:

Add more specificity to your instructions
Include concrete examples of expected output
Add validation steps (”Before outputting, verify that...”)

Errors when running scripts:

Check that dependencies are listed in frontmatter
Verify scripts work standalone before bundling
Check file paths are relative to the skill directory

Keep skills focused. One skill per workflow. Multiple focused skills compose better than one massive skill.
Write clear descriptions. This is the trigger mechanism — invest time here.
Include examples. They’re the most effective way to steer output quality.
Explain the why. Claude generalizes better from reasoning than from rigid rules.
Test with realistic prompts. Use the kind of language real users actually type, including casual phrasing and typos.
Iterate. The first draft is rarely the best. Test, get feedback, improve.
Use progressive disclosure. Keep SKILL.md lean; put detailed references in separate files.

Don’t make skills too broad. A skill that tries to do everything will do nothing well.
Don’t rely on ALL-CAPS rules. Explaining why something matters is more effective than shouting.
Don’t skip the description. Without a good description, Claude won’t know when to use your skill.
Don’t hardcode paths or environments. Skills should be portable across surfaces.
Don’t assume your skill runs in isolation. Claude can load multiple skills simultaneously.

Review skills from external sources before enabling them — check bundled scripts and dependencies
Skills can instruct Claude to install third-party packages, which carries inherent risk
Be cautious of skills that instruct Claude to connect to external network sources
Never include API keys, passwords, or secrets in skill files

Brand guidelines — colors, fonts, tone, logo usage rules
Document templates — structure, formatting, example sections, assets
Code standards — linting rules, naming conventions, review checklists
Data workflows — processing scripts, output formats, chart preferences
Writing style — voice, tone, word choices, formatting, examples
API integration — endpoint docs, auth patterns, request/response examples
Onboarding guides — step-by-step processes, checklists, reference docs

☐ Create a folder named after your skill (lowercase-kebab-case)
☐ Write a SKILL.md with YAML frontmatter (name + description)
☐ Write clear instructions in the Markdown body
☐ Add examples of expected input and output
☐ (Optional) Add scripts/, references/, or assets/ folders
☐ ZIP the folder (skill folder as root of the archive)
☐ Upload in Customize → Skills
☐ Toggle the skill on
☐ Test with realistic prompts
☐ Iterate based on results

That’s the full picture — from a blank folder to a production-ready skill running across Claude.ai, Claude Code, and the API. If you build something cool, I’d love to hear about it. Reply to this email or tag me — I might feature it in a future issue.

Coming up in the newsletter: more deep dives on Claude’s tooling ecosystem, practical AI workflows for dev teams, and hands-on guides like this one. If you found this useful, share it with a colleague who’s still copy-pasting the same prompt every morning.

This newsletter is part of AI For Developers — a growing directory of AI developer tools, APIs, frameworks, and resources. If you’re evaluating tools for your stack or just want to stay on top of what’s out there, check it out:

🔗 AI For Developers — Browse the directory

📬 AI For Developers newsletter — Subscribe to the newsletter

Every issue covers one topic in depth — no fluff, no hype, just the stuff you need to build with AI. Subscribe if you haven’t already, and I’ll see you in the next one.

The Complete Guide to Creating and Using Claude Skills 2026

Comments