The Complete Guide to Creating and Using Claude Skills 2026

TLDR: Claude Skills are reusable expertise packages combining instructions, scripts, templates, and reference materials that work across Claude.ai, Claude Code, and the API—triggered by description matching and loaded efficiently in layers.

Summary: Skills let you stop re-explaining the same context, the same formatting rules, and the same workflow every new conversation. You encode it once as a skill, and Claude applies it automatically whenever it's relevant. A skill can be as simple as brand guidelines or as complex as a multi-file package with executable Python scripts, templates, and reference documents.

Every skill is a folder containing at minimum a SKILL.md file with YAML frontmatter and markdown instructions. The structure is flexible—add scripts/ for executable code, references/ for selectively-loaded documentation, assets/ for templates and images. The frontmatter requires name (lowercase-kebab-case identifier) and description (the primary trigger mechanism). Optional fields include dependencies (packages the skill needs) and license information.

The description field is critical. Claude reads every skill's description to decide whether to load it. A weak description means your skill never triggers. A strong description is specific about what the skill does and when to use it. Include trigger phrases, contexts, even related keywords. Be pushy—Claude tends to under-trigger skills, so err on the side of over-describing when it should activate. A good description is more valuable than perfect formatting.

The body of SKILL.md tells Claude how to do the work. Structure instructions in imperative form—direct commands, not suggestions. Explain the why, not just the what. Claude generalizes better from reasoning than rigid rules. Include concrete examples of input and output. Examples are one of the most effective ways to steer behavior. Define output formats explicitly using templates. If your skill is getting long, move reference material into separate files and point to them from SKILL.md. Skills use a three-level loading system. Metadata (name and description) is always loaded. The SKILL.md body loads when the skill triggers. Bundled resources load on demand. This keeps your context efficient while supporting unlimited reference size.

For deterministic tasks like data processing or file conversion, bundle scripts in a scripts/ directory and reference them from SKILL.md. Dependencies must be listed in frontmatter. Claude can install packages from PyPI and npm at runtime in claude.ai and Claude Code. For API usage, pre-install dependencies in your container.

For large bodies of knowledge that Claude should consult selectively, use a references/ directory with multiple markdown files. For templates, images, fonts, or other assets used in output, create an assets/ directory. Test with realistic prompts—use the language real users actually type, including casual phrasing and typos. Iterate. The first draft is rarely the best.

Skills are discoverable in Claude.ai by going to Settings → Customize → Skills. Click Upload Skill, select your .zip or .skill file, and toggle it on. For Claude Code, skills are discovered automatically from ~/.claude/skills/ or your project's .claude/skills/ directory. You can also invoke them directly with /skill-name-here.

Place skills at project level in .claude/skills/ for team sharing or user level in ~/.claude/skills/ for personal use across projects. To share a skill, open it in Customize → Skills and share with specific people (grayed out until they enable) or your entire organization (published to org directory). Shared skills are view-only—recipients can enable and use but not edit. Updates you make are automatically pushed. Alternatively, package as ZIP and share directly for recipients to upload themselves.

Upload skills via the Skills API with curl, specifying display_title and multipart files. Test immediately after uploading by opening a new chat and triggering the skill explicitly ("Use my skill-name to...") and implicitly (with language that should trigger it). Check edge cases and unexpected inputs.

Avoid common pitfalls: Don't make skills too broad—one skill per workflow. Focused skills compose better than massive catch-alls. 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 external skills before enabling—check bundled scripts and dependencies for security. Skills can instruct Claude to install third-party packages. Be cautious of skills that connect to external network sources. Never include API keys, passwords, or secrets in skill files.

Good candidates for skills: brand guidelines (colors, fonts, tone), document templates (structure, formatting, examples), code standards (linting rules, naming, review checklists), data workflows (processing scripts, output formats), writing style (voice, tone, word choices), API integration (endpoint docs, auth patterns), onboarding guides (step-by-step processes, checklists).

Key takeaways:

Description is the trigger mechanism—invest time making it specific with context and use cases
Skills 2.0 are executable workflows, not just saved prompts—they bundle scripts, templates, and resources
Three-level loading keeps context efficient while supporting complex workflows
Focused skills that do one thing well compose better than broad kitchen-sink implementations

Why do I care: Skills are how you scale Claude workflows across teams without constantly re-explaining yourself. Well-designed skills turn Claude from a general assistant into a specialized tool tailored to your team's exact processes.

The Complete Guide to Creating and Using Claude Skills 2026