Claude Skills: How to Create, Connect, Upload & Improve (2026)

Claude Skills: How to Create, Connect, Upload & Improve (2026)

Most people use Claude the same way every session: paste context, retype instructions, re-explain their workflow, and wait. Skills eliminate all of that. They are the most powerful and underused feature in the Claude ecosystem — a way to package your expertise, your brand rules, your business process, or even a brand-new capability into a file Claude reads automatically, without you ever repeating yourself again.

This guide covers everything: what Claude Skills are architecturally, the difference between Claude.ai and Claude Code skill systems, exact steps to create a SKILL.md from scratch, how to upload or install skills, how to improve performance when a skill underperforms, how to reduce token usage, and 10 real-world examples — including the exact skills that power the Build Fast with AI content engine.

1. What Are Claude Skills? The Architecture

A Claude skill is a folder containing a SKILL.md file — a markdown document with YAML frontmatter at the top and natural-language instructions in the body — that teaches Claude how to handle a specific class of task in a repeatable, consistent way. It is the closest equivalent Claude has to a plugin or a standing operating procedure.

The architecture that makes skills efficient is called progressive disclosure. When Claude starts a session, it reads only the name and description from each installed skill — roughly 100 tokens per skill. When you assign it a task, Claude checks whether any description matches. If a match is found, the full skill content loads (capped at 5,000 tokens). Supporting scripts load only when explicitly needed. The result: you can have 50+ skills installed and unrelated tasks carry zero overhead.

Skills are not always active — they are auto-discovered. This is the part that trips people up most. A vague description means the skill rarely fires. A specific, pattern-matched description means it triggers reliably every time. The Claude AI complete guide for 2026 covers how skills fit within the broader Claude ecosystem alongside Claude Code, Cowork, and MCP.

There are two types of skills worth understanding before you build anything:

Capability Uplift Skills

These give Claude abilities it does not have natively. Before the skill, Claude cannot reliably generate a production-quality .docx file with correctly formatted hyperlinks. After the docx skill, it can. These skills typically include executable Python or Bash scripts in a scripts/ subfolder alongside the SKILL.md, giving Claude real code to run rather than just instructions to follow.

Encoded Preference Skills

These encode your specific way of doing something Claude already knows how to do. Claude can write a blog post — but your skill encodes your exact heading structure, no-em-dash rule, required metadata block, and linking format. Claude can write a tweet — but your skill encodes the 22-signal scoring system, IST posting times, and biological trap post structure. Encoded Preference skills are often just a SKILL.md with no supporting code, and they are the most immediately valuable category for teams and solo operators alike.

2. Two Skill Systems: Claude.ai vs Claude Code

The most critical distinction to understand: "Claude Skills" refers to two different feature systems that share a name and a file format but work differently.

The underlying SKILL.md format is identical. A skill you write works on both surfaces. The difference is access mechanism and advanced execution features, which are Claude Code-specific.

For Enterprise and Team plans on claude.ai, organization owners can provision skills workspace-wide from Organization Settings > Skills. These appear for every team member with a team indicator and can be toggled on or off individually.

3. How to Create a Skill: SKILL.md Structure

A SKILL.md file has two required parts: a YAML frontmatter block at the top (delimited by ---) and a markdown body containing the instructions. Here is the minimal required structure:

--- name: your-skill-name description: "Trigger sentence: exactly when Claude should use this skill." ---  # Skill Title  ## What This Skill Does [One paragraph explaining the goal]  ## Workflow [Step-by-step instructions for Claude]  ## Output Format [Exact format, structure, rules for output]  ## Rules [Constraints, edge cases, things to never do]

The Description Field: The Most Important Part of Any Skill

The description is what Claude reads to decide whether to load your skill. Most skills fail because their description is too vague. The description should read like a trigger specification, not a marketing tagline.

Bad: "Helps with writing tasks."

Good: "Use this skill whenever the user asks to write, draft, or create a tweet, X post, thread, quote-tweet, or reply on X (formerly Twitter). Also trigger when the user shares a topic, news item, link, or rough idea and wants it shaped into an X post. Covers all formats: single tweets, short threads, quote-tweets, reply-jacks, and posts with image/video."

The good description includes: exact trigger phrases, format variants, what IS and IS NOT covered, and an explicit instruction for when to use it even on ambiguous requests.

YAML Frontmatter Fields

• name (required): kebab-case identifier, used in /skills list and plugin installs
• description (required): the trigger specification — this is what Claude reads first
• version (optional): semantic version string, e.g. "1.0.0"
• license (optional): e.g. "MIT" or "Proprietary"
• author (optional): your name or org

When to Add Supporting Scripts

Add a scripts/ subfolder when your skill needs Claude to run actual code — generating files, calling APIs, processing data. The gen-ai-experiments cookbook repository has practical examples of skills that include Node.js scripts for document generation, Python scripts for data validation, and Bash scripts for file operations.

4. How to Upload a Skill to Claude.ai

For Claude.ai users (claude.ai in browser or desktop app), skills are uploaded through the Settings interface. Here is the exact flow:

1. Step 1: Create your skill folder with SKILL.md (and any scripts/ subfolder if needed)
2. Step 2: Zip the folder: right-click the folder > Compress to ZIP, or run zip -r my-skill.zip my-skill/
3. Step 3: Open Claude.ai > click your profile icon (top right) > Settings
4. Step 4: Navigate to Skills (in the left sidebar)
5. Step 5: Click "Upload Skill" and select your .zip file
6. Step 6: Review the skill name and description in the confirmation dialog
7. Step 7: Click "Enable" to activate it immediately in future conversations

Once uploaded, the skill appears in your Skills list with a toggle. You can enable or disable individual skills per conversation using the Skills menu at the bottom of any chat window.

For Organization Admins (Team & Enterprise)

Go to Organization Settings > Skills > Upload Skill. Uploaded skills are automatically provisioned to all members with a team badge. Members can toggle them off individually but cannot remove org-managed skills. This is the fastest way to standardize AI workflows across a team — one upload, everyone gets the same behavior.

5. How to Install Skills in Claude Code

Claude Code skills live in one of two locations: ~/.claude/skills/ for personal installs (available across all projects) or .claude/skills/ inside a specific repo (project-scoped, shared via git). Three installation methods exist, from fastest to most manual.

Method 1: Plugin Marketplace (Fastest)

In any Claude Code session, type /plugin to open the plugin browser. Navigate to the Discover tab, find the skill, press Enter to install. Claude asks whether to install as User (all projects) or Project (current repo only).

/plugin install frontend-design@anthropic-agent-skills # Add a third-party marketplace: /plugin marketplace add agensi

Method 2: curl One-Liner (Agensi Skills)

For skills from Agensi (the largest security-scanned marketplace), a single command installs directly:

mkdir -p ~/.claude/skills && curl -sL https://www.agensi.io/api/install/SKILL_SLUG | tar xz -C ~/.claude/skills/

Method 3: Manual Installation (GitHub or Custom)

# For personal install (all projects): cp -r my-skill-folder/ ~/.claude/skills/  # For project install (current repo only): cp -r my-skill-folder/ .claude/skills/  # Verify loaded: /skills

To temporarily disable a skill without deleting it, rename the folder with a leading underscore: _my-skill-name. Claude Code ignores folders starting with underscore. Restart the Claude Code session after any install or rename.

6. How to Connect Skills to MCP Servers

Skills and MCP servers are complementary, not competing. MCP is the kitchen — the knives, pots, and ingredients (the tools and connections to external services). A skill is the recipe — the instructions for how to use them to produce a specific output. The best way to understand when to combine them: read the Claude MCP setup guide for 2026 first, then layer skills on top.

To reference an MCP server inside a skill, add a tools_required field to your SKILL.md frontmatter and describe how Claude should use the connected service in the workflow section:

--- name: github-pr-reviewer description: "Use when reviewing pull requests or creating PR summaries..." tools_required:   - github-mcp ---  ## Workflow 1. Use the github MCP server to fetch the PR diff 2. Apply the review checklist below 3. Return structured feedback in the required format

Claude loads the skill when the trigger fires, sees the tools_required annotation, and knows to look for that MCP connection. If the MCP server is not active, Claude will note the missing dependency rather than silently failing.

7. How to Improve Skill Performance

A skill that rarely triggers, produces inconsistent output, or misses edge cases has one of five problems — each with a specific fix.

Problem 1: The Skill Does Not Trigger Reliably

Root cause: description is too vague. Fix: make the description a trigger specification. List the exact phrases a user would type, include all format variants, and add an explicit "Also trigger when..." clause for ambiguous phrasing. Use the Skill Creator to run automated evals — it splits test prompts 60/40, measures trigger rate, and picks the highest-scoring description variant.

Problem 2: The Skill Triggers for the Wrong Tasks

Root cause: description is too broad. Fix: add an explicit "Do NOT use for..." section at the end of the description. Every BFWAI skill has this — for example, the blog-writer description explicitly excludes Unrot news cards, and the x-algo-tweet-writer explicitly excludes LinkedIn posts. This prevents bleed between similar-purpose skills.

Problem 3: Output Quality Is Inconsistent

Root cause: the workflow section is ambiguous. Fix: add a mandatory elements checklist at the end of the skill. A checklist makes Claude verify its own output before responding. The blog-writer skill uses a 40+ item checklist covering every required section, every link type, and every formatting constraint.

Problem 4: Claude Ignores Parts of the Skill

Root cause: instructions buried mid-document. Fix: put the most important rules at the top of the skill body, not the bottom. Claude reads SKILL.md files sequentially. If the most critical constraint is in paragraph 12, it may be de-prioritized in long contexts. Restructure with the output format and hard rules first, the detailed workflow second.

Problem 5: The Skill Works Once But Degrades Over a Long Conversation

Root cause: context window compression over a long chat. Fix: add a self-check instruction inside the skill — "Before responding, verify your output against the mandatory checklist." This re-activates the skill constraints mid-conversation. For more on prompt engineering patterns that reinforce behavior, the Claude prompt engineering guide covers XML tagging and constraint reinforcement techniques that pair directly with skill design.

8. How to Reduce Token Usage and Context Limits

Every skill file is injected into Claude's context window when it triggers. If your skills are large, you will hit rate limits faster, especially on Claude Pro (which enforces per-session context usage limits). Here are the practical strategies:

Keep SKILL.md Files Under 3,000 Tokens

The recommended cap is 5,000 tokens per skill, but 3,000 is the practical target for comfortable headroom. Run your SKILL.md through a token counter (the Anthropic tokenizer or tiktoken) before deploying. If it exceeds 3,000 tokens, identify redundant prose and replace with structured rules or tables.

Use Reference Files Instead of Inline Content

Instead of pasting a 2,000-word writing style guide directly into the SKILL.md, store it as a reference file (references/writing-voice.md) and instruct Claude to read it only when writing content sections. This keeps the base skill lean and loads the heavy content on demand.

Split Large Skills Into Sub-Skills

A 6,000-token "content creation skill" that covers blogs, tweets, news cards, and email newsletters is worse than four 1,200-token skills, each with a tight description. Smaller skills with precise descriptions mean only the relevant one loads per task — the others cost zero tokens.

Avoid Repeating Information Across Skills

If five of your skills all include your brand voice guidelines, that's five copies loading context whenever any of them fires. Create a single brand-voice.md reference file and point to it from each skill's description with a "read references/brand-voice.md before writing" instruction.

Use the Skill Creator Eval Loop

The Skill Creator (pre-installed in Claude Desktop) runs an optimization loop that not only improves trigger accuracy but also trims skill content. Run /skill-creator on existing skills, not just new ones — it often identifies sections that can be shortened by 40% without any loss of output quality.

9. Ten Real-World Claude Skill Examples

These ten skills represent the range of what the skill system can do — from capability uplift to encoded preference, from solo operators to enterprise teams.

1. blog-writer (Encoded Preference + Capability Uplift)

Produces full SEO/AEO/GEO-optimized blog posts as .docx files. Trigger: any request to write a blog post or create SEO content. The skill runs a 6-phase workflow: sitemap scan to build an internal link pool, keyword research block, article structure, writing with voice rules, inline link placement, and Word document generation via a Node.js script. Output includes 40+ mandatory element checks. Used daily to produce ranked content for buildfastwithai.com.

2. unrot-news-card-writer (Encoded Preference)

Produces punchy 75-word micro-learning news cards for the Unrot app. Trigger: "write a news card about..." or "Unrot article about...". The skill enforces a strict output structure: headline, two-paragraph body under 75 words, three key bullet points — the exact format the Unrot card component renders. Without this skill, news cards require manual reformatting every time. With it, output is copy-paste ready.

3. x-algo-tweet-writer (Encoded Preference)

Writes algorithm-optimized X posts using 22 engagement signals derived from the leaked xAI source code. Trigger: any request to write a tweet, thread, or reply. The skill applies the biological trap post structure, IST posting time optimization, radical restraint rules for hashtag use, and a scoring rubric before output. A tweet written with this skill performs measurably differently from a generic AI draft.

4. frontend-design (Capability Uplift — Official Anthropic)

The most-installed skill in the marketplace with 277,000+ installs. Gives Claude a complete design system before it touches any UI code: typography decisions, spacing scales, color palette principles, component patterns. Without it, most Claude-generated UIs converge on the same "Inter font, purple gradient" default. With it, Claude produces distinctive, intentional design instead of templated output.

5. docx (Capability Uplift)

Gives Claude the ability to generate production-quality Word documents via the docx npm package. The skill includes detailed instructions for US Letter page sizing, Arial typography, navy H1 (#1F3864), blue H2/H3 (#2E75B6), correct table construction with DXA widths, ExternalHyperlink usage, numbered list configuration, and a validate.py script for post-generation quality checks. Without this skill, Claude-generated .docx files are structurally inconsistent.

6. spy (Capability Uplift)

Competitor ad surveillance via the Meta Ad Library. Trigger: "/spy [brand]" or "spy on [competitor]". The skill fetches every active ad for a Facebook page, diffs against the last saved pull to surface only NEW creative, and outputs a structured intelligence report: hooks, CTAs, offer types, creative angles, and ad longevity. It identifies 30+ day runners as proven winners automatically.

7. code-reviewer (Encoded Preference)

Systematic pull request review with configurable focus areas: security vulnerabilities, performance bottlenecks, style consistency. The skill outputs structured review comments in a format that maps directly to GitHub PR comments — severity label, exact file location, explanation, and corrected code snippet. Configurable by adding focus directives to the trigger prompt: "code-review this PR, focus on security."

8. topic-research-brief (Encoded Preference + Capability Uplift)

Deep research on any topic before writing content. Runs 8-15 web searches, reads the buildfastwithai.com sitemap, scans the gen-ai-experiments cookbook repo, and returns a single structured intelligence report covering: search intent, PAA questions, organic keywords, latest news, related published blogs, and relevant cookbooks. Feeds directly into the blog-writer skill as its input phase.

9. bfwai-daily-twitter (Capability Uplift — research-heavy)

Generates a full daily Twitter/X content brief by running live research: AI news, GitHub trending repos, and developer Twitter. Output: top discussable topics, oversaturated topics to avoid, five high-quality tweet drafts, two thread ideas, three targeted reply ideas, and optimal posting times. The skill cannot run without web search access — this is a research-dependent Capability Uplift skill, not a pure preference encoder.

10. skill-creator (Meta-skill — Official Anthropic)

Builds new skills from scratch through an interactive Q&A. Describes the workflow, collects examples, generates a complete skill directory with proper SKILL.md structure, then runs an optimization loop. Splits example prompts 60/40 into train/test sets, measures trigger rate across test prompts, generates improved description variants, and picks the highest-scoring version by test score. This is the skill that builds all your other skills. Install first before building anything manually.

10. Skills vs MCP vs Subagents: When to Use What

The Claude ecosystem has four extensibility mechanisms that people regularly confuse. Here is a clean decision framework. For detailed MCP setup and connection instructions, see the Claude MCP complete guide.

Mechanism

Skills

Encoding repeatable workflows, brand rules, output formats, task-specific expertise

One-off tasks, connecting external services, parallelizing long tasks

MCP Servers

Connecting Claude to external systems: GitHub, Slack, databases, APIs, file systems

Encoding task instructions — MCP provides tools, not workflows

Subagents

Parallelizing large tasks, running isolated subtasks with separate context windows

Simple sequential tasks that one Claude instance handles fine

CLAUDE.md

Project-level memory: repo structure, coding standards, team conventions that apply to every task in a project

Task-specific workflows — those belong in skills, not CLAUDE.md

Frequently Asked Questions

What is a Claude skill in simple terms?

A Claude skill is a reusable instruction package stored in a SKILL.md file that tells Claude exactly how to handle a specific type of task. Think of it as an SOP (standard operating procedure) Claude reads automatically when the right trigger phrase appears in your prompt — no re-explaining required.

Can I use Claude Skills without Claude Code?

Yes. Claude.ai users can upload skills as a .zip file through Settings > Skills. This works in the browser, desktop app, and mobile app. Claude Code offers additional features (plugin marketplace, project-scoped installs, script execution hooks) but is not required to use skills.

How many skills can I install before performance degrades?

Claude reads only the name and description (roughly 100 tokens per skill) at session start. With well-scoped skills under 3,000 tokens each, 30-50 skills is practical with no meaningful overhead on unrelated tasks. The key is keeping descriptions precise so only relevant skills load.

What is the difference between a skill and a system prompt?

A system prompt is manually injected into every conversation and always occupies context. A skill loads only when its trigger fires. For repeated specialized tasks, skills are more efficient. For global behavior you want in every conversation regardless of task, a system prompt is the right tool. Most production setups use both.

How do I know if my skill is triggering correctly?

In Claude Code, run /skills to see the list of installed skills and their trigger status. Ask Claude directly: "Which skills are currently loaded?" Claude will report what fired for your request. For systematic testing, use the Skill Creator's eval loop — it runs your trigger test set automatically and reports a trigger rate percentage.

Can skills access the internet or run code?

Yes, with the right setup. Skills can reference web search tools and MCP servers in their frontmatter. Skills can include executable Python or Bash scripts in a scripts/ folder that Claude Code runs as part of the workflow. Claude.ai skills can use web search if the search tool is enabled in your session. Capability depends on what tools are active in your environment, not on the skill format itself.

Are skills private or can others see them?

Skills you upload to claude.ai are private to your account (or your organization's workspace for Team/Enterprise). Skills installed in Claude Code live on your local machine and are private unless you publish them to a marketplace or push the .claude/skills/ folder to a shared git repository.

What is the token limit for a SKILL.md file?

The official recommended limit is 5,000 tokens for the full skill content. The practical target for comfortable headroom is 3,000 tokens. Supporting scripts in the scripts/ folder only load when explicitly needed and do not count against the skill's base footprint.

Recommended Blogs

• Claude AI Complete Hub 2026 — Everything Claude, Skills, Code & Cowork
• Claude Skills: The Complete 2026 Guide — Build, Install & Use
• Claude MCP Setup Guide: Connect Any Tool in 10 Minutes (2026)
• 150 Best Claude Prompts That Work in 2026
• Claude AI Prompt Codes That Actually Work (2026)
• Claude AI 2026: Models, Features, Desktop & More

References

• Anthropic — Agent Skills Overview (Claude API Docs)
• Build Fast with AI — Claude Skills: The Complete 2026 Guide
• Anthropic — Prompt Engineering Overview
• Medium (unicodeveloper) — 10 Must-Have Skills for Claude in 2026
• Build Fast with AI — Claude MCP Setup Guide 2026
• GitHub — buildfastwithai/gen-ai-experiments
• Anthropic — Equipping Agents for the Real World with Agent Skills (Engineering Blog)