Anthropic’s Agent Skills format has quietly become one of the most-searched features in the Claude ecosystem. “Claude code skills” now pulls roughly 12,100 monthly US searches, and terms like “claude skills marketplace” and “claude skills github” add thousands more, according to keyword data pulled in September 2026. Yet most of what shows up when you search is either dry API reference or a scattered GitHub directory. This tutorial walks through the entire process: what a Skill actually is, how to write a valid SKILL.md file, how to test it locally in Claude Code, and how to package and share it with a team or the wider community. By the end you will have a complete, working custom skill installed and running.
The format matters because it changes how you work with Claude day to day. Instead of pasting the same instructions into every new chat, you write them once as a Skill, and Claude loads them automatically when the conversation calls for it. Anthropic made Computer Use, the Skills API, and the Files API generally available on the Claude Platform on August 20, 2026, and the underlying Skill contract has stayed stable since: a folder, a SKILL.md file, and optional supporting scripts. That stability is exactly what makes it worth learning properly rather than copy-pasting a template you don’t understand.
Don't miss new tech stories on Google
Add Tech Insider once in the Google app and our stories appear in your news suggestions.
What Claude Agent Skills actually are
An Agent Skill is a self-contained folder that gives Claude a repeatable operating procedure for a specific kind of task. Anthropic’s own framing, published in its Agent Skills overview, describes skills as reusable, filesystem-based resources that hand a general-purpose agent domain-specific workflows, context, and best practices. The distinction that trips people up first: a Skill is not a prompt. A prompt is something you type into a single conversation. A Skill sits on disk, gets discovered automatically, and loads only when Claude judges it relevant to the task at hand.
Every Skill bundle needs exactly one required file: SKILL.md, placed at the top level of the skill’s folder. That file has two parts. A YAML frontmatter block declares the skill’s name and description, and the Markdown body underneath contains the actual instructions Claude follows once the skill loads. You can also drop in supporting files next to it: shell scripts, Python helpers, templates, config files, sample data, anything the instructions reference.
This is the same mechanism behind the built-in skills you may already use inside Claude Code, including /verify and /code-review. Anthropic’s Claude Code release notes for August 8, 2026 confirm that both of those shifted from running automatically to requiring an explicit /verify or /code-review invocation, which is a useful early signal that Claude’s own team treats Skills as commands you control rather than background magic. If you want a deeper look at how Claude assembles context and calls tools around a Skill invocation, our Claude Agent SDK tutorial covers the lower-level primitives this system is built on.
Prerequisites and versions you’ll need
Before starting, confirm you have the right tooling installed. Skills work slightly differently depending on where you run them, so this tutorial focuses on Claude Code, the most common entry point, and notes API/Platform differences along the way.
- Claude Code CLI, bundled version 2.1.255 or newer as of the September 3, 2026 changelog entry (run
claude --versionto check; update with your package manager or the official installer if you’re behind) - An active Claude.ai, Claude Pro, Claude Max, or Claude Platform (API) account with billing configured if you plan to test with metered API calls
- A terminal with Git installed (2.30 or newer is fine) for cloning reference skills and version-controlling your own
- A text editor that handles YAML frontmatter cleanly — VS Code, Zed, or any editor with Markdown syntax highlighting works
- Python 3.10+ or Node.js 18+ only if your skill will ship helper scripts; plain instruction-only skills need neither
- Basic familiarity with Markdown and YAML syntax — this tutorial assumes you can write a bullet list and a key-value pair without a reference sheet
None of this requires a paid tier to experiment. You can build and test custom skills locally inside Claude Code on a free or Pro account. Publishing to an organization workspace via the Skills API, covered later in this tutorial, does require a Claude Platform account with workspace admin permissions.
Step 1: Decide what problem the skill solves
Skip this step and you’ll end up with a vague, bloated skill that Claude never invokes correctly. Before writing a line of Markdown, write one sentence describing the trigger condition and one sentence describing the expected output. For example: “When a user asks me to review a pull request diff for security issues, walk through the OWASP Top 10 checklist and flag any matches with file and line references.” That sentence becomes the backbone of your description field later.
Good first skills tend to automate something you already do manually and repeatedly: a commit message format, a changelog structure, a specific data-cleaning routine, a company style guide for documentation. Bad first skills try to cover too much ground (“help with all backend tasks”) and end up competing with Claude’s own general reasoning instead of adding anything.
Step 2: Create the skill’s folder structure
Claude Code discovers project-level skills at an exact path, one directory level deep from the project root: .claude/skills/<skill-name>/SKILL.md. If you want the skill available across every project on your machine instead of just one repo, place it under your home directory at ~/.claude/skills/<skill-name>/SKILL.md. Both paths follow the identical bundle format; the only difference is scope.
mkdir -p .claude/skills/pr-security-review
cd .claude/skills/pr-security-review
touch SKILL.mdThe folder name itself should match the name field you’ll declare in the frontmatter. Keep it short, lowercase, and hyphenated — Anthropic’s spec caps the name field at 64 characters and restricts it to lowercase letters, numbers, and hyphens only, with no XML tags permitted anywhere in the value.
Step 3: Write the YAML frontmatter
Open SKILL.md and start with the frontmatter block, delimited by triple-dash lines. Two fields are mandatory: name and description. The description field is the single most important piece of writing in the entire skill, because it’s what Claude scans to decide whether a given conversation should trigger this skill. Anthropic’s documentation is explicit that the description must state both what the skill does and when Claude should use it — a description that only says what it does, without the trigger condition, causes the skill to load too rarely or too often.
---
name: pr-security-review
description: >
Reviews a pull request diff for common security issues using an
OWASP-aligned checklist. Use this skill whenever the user pastes a
git diff, asks for a security review of code changes, or asks
"is this PR safe to merge" or similar phrasing.
---The description field has a hard ceiling of 1,024 characters and, like name, cannot contain XML tags. If you’re publishing through the Skills API rather than a local folder, you can also set an optional display_name field at the upload layer — up to 255 characters, and unlike name it doesn’t need to be unique within a workspace, since it’s a display label rather than an identifier.
Common frontmatter mistakes
A capital letter or underscore in name will fail validation outright. A description that’s purely generic (“helps with code”) gives Claude nothing to match against and the skill effectively never fires. And a description that’s too narrow (“only for reviewing diffs in the auth.py file”) means the skill misses every legitimate use case outside that one file. Aim for specific but not brittle.
Step 4: Write the instruction body
Everything below the closing --- is regular Markdown, and this is where the actual operating procedure lives. Structure it the way you’d document a process for a new hire: numbered steps, explicit constraints, and concrete examples of good and bad output. Claude reads this content in full once the skill is loaded, so vague prose costs you nothing in reliability, but it does cost you in quality — the more concrete your instructions, the more consistent the output.
# PR Security Review
When reviewing a diff, work through these checks in order:
1. Injection risks — flag any string concatenation into SQL,
shell commands, or template rendering without parameterization.
2. Authentication/authorization — flag any new or modified route
that lacks an explicit permission check.
3. Secrets — flag any hardcoded API key, token, or password,
even in test fixtures.
4. Deserialization — flag any use of pickle, eval, or unsanitized
YAML loading on user-controlled input.
5. Dependency changes — flag any new dependency with fewer than
1,000 GitHub stars or no commits in the last 12 months.
For each finding, report: file path, line number, severity
(critical/high/medium/low), and a one-sentence fix suggestion.
Do not report a finding you are not at least 70% confident about;
list uncertain items separately under "worth a second look."Notice the last paragraph in that example: an explicit confidence threshold. Skills that don’t set boundaries on what counts as a reportable finding tend to flood output with noise. Writing the boundary directly into the skill is far more reliable than hoping Claude infers it from context each time.
Step 5: Add supporting scripts and resources (optional)
If your skill needs to run actual code rather than just follow instructions, drop the script into the same folder and reference it from SKILL.md. A common pattern is a Python or shell script that does deterministic work — formatting, linting, data transformation — while the Markdown instructions tell Claude when and how to call it.
.claude/skills/pr-security-review/
├── SKILL.md
├── scripts/
│ └── check_dependencies.py
└── reference/
└── owasp-checklist.mdIn SKILL.md, tell Claude explicitly when to reach for the script: “Run scripts/check_dependencies.py <path-to-package-file> to get a machine-readable dependency risk report before writing the final summary.” Claude will read the script’s output as part of its context and fold it into the response. This is also how progressive disclosure works in practice — Claude doesn’t load every file in the skill folder up front, it reads the instructions, decides what it needs, and pulls in reference files or runs scripts only as required.
Step 6: Validate the skill locally
Before you trust a skill, check it against the spec manually. There’s no dedicated linter shipped as of this writing, so a quick shell check catches the most common formatting errors: missing frontmatter delimiters, a name with invalid characters, or a description that’s empty.
#!/bin/bash
# quick-validate.sh — sanity-check a SKILL.md file
FILE=".claude/skills/pr-security-review/SKILL.md"
grep -q "^---$" "$FILE" || echo "FAIL: missing frontmatter delimiter"
NAME=$(grep "^name:" "$FILE" | cut -d' ' -f2)
echo "$NAME" | grep -Eq '^[a-z0-9-]{1,64}$' || echo "FAIL: invalid name field"
grep -q "^description:" "$FILE" || echo "FAIL: missing description field"
echo "Validation complete for $FILE"Save that as quick-validate.sh, run chmod +x quick-validate.sh, then execute it against every skill before you commit it. It won’t catch everything — it doesn’t check the 1,024-character description limit, for instance — but it catches the errors that silently break discovery.
Step 7: Test invocation inside Claude Code
Start a Claude Code session from inside the project directory where your .claude/skills/ folder lives. There are two ways to trigger a skill: contextually, by asking a question that matches the description, or explicitly, using a slash command. The community-maintained Awesome Claude Skills directory, which currently lists 204 skills across 13 categories, documents both patterns and notes that explicit invocation follows the /skill-name convention.
› /pr-security-review
› paste your diff here, or ask:
"Can you check this PR for security issues before I merge it?"If the skill was written correctly, Claude will announce that it’s using the skill (interfaces typically surface this as a small indicator or a stated line like “Using skill: pr-security-review”) and then follow the numbered procedure from your instructions. If nothing happens, the description almost certainly isn’t specific enough, or the file isn’t sitting at the exact discovery path — check for a typo in the folder name.
Step 8: Check example output against your goal
Run the skill against a real, messy example — not a clean toy case. For the PR security skill above, a realistic test run against a diff with a hardcoded token and an unparameterized SQL query should produce something close to this:
Findings:
1. [CRITICAL] auth/tokens.py:14 — Hardcoded API key in
DEFAULT_TOKEN constant. Move to environment variable
and rotate the exposed key.
2. [HIGH] db/queries.py:47 — User-supplied `username` is
concatenated directly into SQL string. Use a
parameterized query instead.
Worth a second look:
- utils/cache.py:22 — New dependency `fastcache==0.4.1`
has 340 GitHub stars and no commits since 2023. Confirm
this is still the right choice.If the actual output drifts from this — say, it misses the hardcoded token or buries it under low-priority noise — that’s a signal to go back and tighten Step 4’s instructions, not a sign the format itself is broken.
Step 9: Iterate on the description field
Most skill failures trace back to the description, not the instructions. If Claude keeps invoking your skill for irrelevant requests, narrow the trigger language. If Claude ignores it when you expect it to fire, broaden the phrasing to cover more of the natural ways someone would ask. Keep a short log of phrasings that failed to trigger the skill during testing and fold the pattern back into the description — this single loop improves reliability more than any other change you can make.
Step 10: Package the skill for sharing
Once a skill works reliably, you’ll usually want teammates to use it too. There are two supported sharing paths as of September 2026, and which one you pick depends on scope.
For informal sharing, commit .claude/skills/ to your project’s Git repository. Anyone who clones the repo and opens it in Claude Code gets the skill automatically, no extra install step required, because discovery is filesystem-based. This is the fastest path and the one most teams use first.
For organization-wide distribution through the Claude Platform, use the Skills API, which Anthropic moved to general availability alongside Computer Use and the Files API on August 20, 2026. The skill format itself didn’t change with that GA release — it’s still a folder with a SKILL.md at the root — but the API adds upload, versioning, and per-request mounting, plus the ability for Team and Enterprise workspace admins to enable a skill for every member or a specific group without anyone copying folders by hand.
# Zip a skill bundle for API upload
cd .claude/skills/
zip -r pr-security-review.zip pr-security-review/
# SKILL.md must sit at the root of the zip, or at the top
# of a single enclosing folder — nested paths will fail
# the upload validation.Step 11: Install skills built by other people
The reverse direction is just as common: pulling in a skill someone else already wrote instead of building from scratch. Anthropic maintains an official public repository of Agent Skills at github.com/anthropics/skills, where each skill is self-contained in its own folder with a SKILL.md holding the instructions and metadata Claude uses. Clone the repository, copy the folder you want into your project’s .claude/skills/ directory, or your global ~/.claude/skills/ directory for machine-wide use, and it’s discoverable on your next session.
git clone https://github.com/anthropics/skills.git /tmp/anthropic-skills
cp -r /tmp/anthropic-skills/document-skills/pdf .claude/skills/pdfThe community directory referenced earlier also documents a plugin-style install flow for packaged bundles: /plugin install <name>@<marketplace>, which places the resulting skills into the expected filesystem path automatically. Either route lands you in the same place — a validated folder under .claude/skills/.
Step 12: Combine skills into a working project
A single skill is useful. A small library of skills working together, scoped to different stages of a workflow, is where the format earns its keep. Here’s a complete, working three-skill setup for a typical software project — a linting/style skill, the security review skill from earlier, and a changelog-writing skill — all discoverable from the same repo.
.claude/skills/
├── pr-security-review/
│ └── SKILL.md
├── style-guide-enforcer/
│ └── SKILL.md
└── changelog-writer/
├── SKILL.md
└── reference/
└── past-entries.mdThe changelog-writer skill’s description would read something like: “Use when the user asks to write or update a changelog entry, or says ‘summarize these commits for the release notes.’ Reference past-entries.md for tone and format consistency.” Because each skill has a narrow, well-defined trigger, Claude picks the right one without you having to specify which skill you mean — that’s the entire point of the format. Committing this folder to the project repo means every teammate and every new Claude Code session gets all three skills for free.
Skills vs. custom instructions vs. MCP servers
New users routinely confuse three overlapping-but-different mechanisms: project-level custom instructions, Model Context Protocol (MCP) servers, and Agent Skills. Each solves a different problem, and picking the wrong one is a common reason people give up on Skills after a bad first impression.
Custom instructions — the text you set once in a Claude.ai project or a CLAUDE.md file in Claude Code — load into every single conversation in that project, whether they’re relevant or not. That’s fine for a handful of always-true facts about your codebase or team conventions, but it gets expensive fast if you pile on instructions for a dozen different specialized workflows. Every token in that file is spent on every request, whether the current task needs it or not.
MCP servers, by contrast, expose live tools and data connections — a database query tool, a ticketing system integration, a search index — that Claude can call during a conversation. They’re the right choice when you need Claude to reach outside its own context window and touch a real system in real time. If you haven’t built one yet, our MCP server tutorial walks through building one in Python with FastMCP.
Agent Skills sit between those two. Unlike custom instructions, they load conditionally, only when the conversation matches the description, so you can maintain dozens of specialized procedures without paying a context tax on every unrelated request. Unlike MCP servers, they don’t require standing up a server process or managing a live connection — they’re just files on disk, versioned like any other project asset. The three mechanisms compose well together: a skill’s instructions can tell Claude to call a specific MCP tool as part of the procedure, and a project’s CLAUDE.md can note which skills exist without repeating their full instructions inline.
| Mechanism | Loads when | Best for | Setup complexity |
|---|---|---|---|
| Custom instructions / CLAUDE.md | Every conversation in scope | Always-true facts, team conventions | Low — one file, no schema |
| Agent Skills | Conditionally, on description match | Repeatable, specialized procedures | Low-medium — frontmatter plus instructions |
| MCP servers | On demand, via tool call | Live data access, external systems | Medium-high — server process, auth, schema |
When a skill is the wrong tool
Skills aren’t the answer to everything. If the task needs live, constantly-changing data — current stock prices, today’s support ticket queue, a database row that changed five minutes ago — a skill’s static instructions can’t fetch that on their own; you need an MCP server or a script the skill calls out to. And if the behavior you want should apply to genuinely every single request in a project with zero exceptions, a short custom-instructions block is simpler and more predictable than writing a skill description broad enough to always match.
Where skills run: supported clients
Custom skills aren’t limited to the CLI. Anthropic’s documentation lists Claude.ai, Claude Code, the Claude Developer Platform (API), Claude on AWS, and Microsoft Foundry as environments where custom skills can run, alongside a set of prefabricated skills for common document tasks — PowerPoint, Excel, Word, and PDF — available out of the box on each. If you’re building with the Agent SDK directly rather than through the CLI, our Claude Agent SDK guide covers how skills are defined as filesystem artifacts your agent configuration points at, and our Claude API tutorial is the right next stop if you’d rather integrate a skill-driven workflow directly through Python.
| Environment | Discovery method | Prefabricated skills? | Custom skill install |
|---|---|---|---|
| Claude Code (CLI) | Filesystem: .claude/skills/<name>/SKILL.md | Yes — verify, code-review, design (preview) | Copy folder or clone from Git |
| Claude.ai (web) | Workspace settings upload | Yes — PowerPoint, Excel, Word, PDF | Upload via settings UI |
| Claude Developer Platform (API) | Skills API bundle upload | Yes — document tasks | Zip upload, versioned, mounted per request |
| Claude Agent SDK | Filesystem artifacts, agent config points to directory | No — bring your own | Copy folder into configured skills path |
| Claude on AWS / Microsoft Foundry | Skills API bundle upload | Yes — document tasks | Zip upload via platform console |
Five common pitfalls when building your first skill
1. Writing a description that only states the topic, not the trigger. “This skill helps with security reviews” tells Claude what the skill is about but not when to reach for it. Always phrase at least part of the description as a trigger condition — “use when the user asks for X” — not just a subject label.
2. Putting the SKILL.md file at the wrong depth. Claude Code’s discovery expects exactly .claude/skills/<skill-name>/SKILL.md, one directory level deep. Nesting it further, or leaving it directly in .claude/skills/SKILL.md without the intermediate folder, means it simply won’t be found.
3. Overloading one skill with unrelated responsibilities. A skill that tries to handle code review, deployment, and documentation all in one file dilutes its own description until it stops matching anything precisely. Split it into three narrow skills instead.
4. Forgetting that the name field is a strict identifier, not a display label. Spaces, capital letters, and underscores in name will fail validation, since the spec permits only lowercase letters, numbers, and hyphens up to 64 characters. Save the friendly wording for the display_name field when you’re uploading through the Skills API.
5. Never testing against messy, realistic input. A skill that works perfectly on a clean toy example and has never been run against real, ambiguous data will surprise you in production. Test with the ugliest example you have before you trust the output.
Recent changes worth knowing about
The Skills feature has moved fast over the past month. The Skills API’s move to general availability on August 20, 2026 was the headline change, adding versioning and per-request mounting on top of the existing folder-based format. Anthropic’s own Claude.ai changelog notes the bundled Claude Code CLI reached version 2.1.255 as of September 3, 2026, and the what’s new page documents cross-session messaging on macOS and Linux, letting one Claude Code session pass a finding to another instead of you re-explaining context by hand.
A research-preview skill called /design shipped on August 17, 2026, taking an idea, a screenshot, or an existing design as input and returning editable artboards built on artifacts, available in both the CLI and the desktop app. And on the security side, Anthropic’s August 17, 2026 release notes describe a fix where remote file reads, session restore, CLAUDE.md includes, and workflow scripts now reject Windows NT-namespace paths, closing off a pre-approval file-access vector that could otherwise leak NTLM credentials — worth knowing if any of your skills reference remote file paths in their supporting scripts.
| Date (2026) | Change | Why it matters for skill authors |
|---|---|---|
| Aug 8 | /verify and /code-review switch to explicit invocation | Confirms Anthropic treats built-in skills as opt-in commands, a pattern worth mirroring in your own skills |
| Aug 17 | NT-namespace path rejection in file access | Closes a credential-leak vector relevant to skills with scripts that touch remote paths |
| Aug 17 | /design research preview ships | Shows Skills extending into visual/artifact-based output, not just text |
| Aug 20 | Skills API reaches general availability | Adds versioned upload and workspace-wide enablement on top of the stable folder format |
| Sep 3 | Claude Code CLI bumped to 2.1.255 | Confirms the minimum CLI version for this tutorial’s steps |
Advanced tips once the basics work
Version your skills the same way you version code. If you’re publishing through the Skills API, attach a specific version number at request time rather than always pulling “latest” — that gives you a rollback path if a description change accidentally makes the skill fire too often or too rarely. For filesystem-based skills shared through Git, tag releases the same way you’d tag any other internal tooling change, so teammates can pin to a known-good version if you’re actively iterating.
Keep supporting reference files small and specific rather than dumping an entire wiki into the folder. Progressive disclosure means Claude reads instructions first and pulls in reference material as needed, but a 40-page reference file still costs context budget once it’s loaded — split large reference material into topic-specific files the instructions can point to selectively.
Write a short “anti-example” into instruction-heavy skills — a description of output you don’t want, not just what you do want. For the PR security skill, that might mean explicitly stating “do not flag standard use of environment variables for configuration” to head off false positives before they happen, rather than discovering the failure mode after a teammate complains.
Finally, treat the description field as a living document. Revisit it every time you notice the skill misfiring, and don’t be afraid to rewrite it entirely rather than patching around a bad first draft — a clean, specific description written from scratch usually beats an accumulation of edge-case caveats bolted onto a vague one.
Troubleshooting: 8 issues and how to fix them
Skill never triggers, even on obviously relevant requests. Almost always a description problem. Rewrite it to include the exact phrasing a user is likely to type, not just an abstract summary of the skill’s purpose.
Skill triggers on completely unrelated requests. The description is too broad. Narrow the trigger language and remove generic terms that could match many different conversations.
“Invalid name” error on validation or upload. Check for capital letters, underscores, spaces, or a length over 64 characters in the name field — only lowercase letters, numbers, and hyphens are permitted.
Skill folder exists but Claude Code doesn’t see it. Confirm the exact path: .claude/skills/<skill-name>/SKILL.md, one level deep from the project root, not nested further and not placed directly in .claude/skills/ without its own subfolder.
Global skill works in one project but not another. Global skills live at ~/.claude/skills/ and should be visible everywhere; if one project doesn’t pick it up, check for a project-level skill with a conflicting name shadowing the global one.
Skills API upload rejected. Confirm SKILL.md sits at the root of your zip, or at the top of a single enclosing folder — a nested path inside the archive fails the upload validation.
Supporting script referenced in SKILL.md never runs. Check that the instructions state the script path explicitly and relative to the skill folder, and that the script itself has execute permissions if it’s a shell script.
Team members see a different version of the skill than expected. If you’re distributing through the Skills API with versioning, confirm which version is mounted per request; if you’re distributing through Git, confirm everyone has pulled the latest commit touching .claude/skills/.
Skill format at a glance
| Field | Required? | Limit | Notes |
|---|---|---|---|
| name | Yes | 64 characters max | Lowercase letters, numbers, hyphens only; no XML tags |
| description | Yes | 1,024 characters max | Must state both purpose and trigger condition; no XML tags |
| display_name | No (API upload only) | 255 characters max | Derives from name if omitted; not required to be unique |
| SKILL.md file placement | Yes | N/A | Top level of skill folder, or root of upload zip |
| Supporting files | No | N/A | Scripts, templates, reference docs; referenced from instructions |
If you’re weighing Claude Code against other AI coding agents before investing time in building a skill library, our Amp vs Claude Code vs Cursor comparison covers how the tooling stacks up on pricing and workflow. And if your skills are going to call out to other tools or APIs as part of their instructions, it’s worth reading up on OpenClaw 2.0’s credential handling changes, since agent tooling security has been moving fast across the whole ecosystem this year.
Frequently asked questions
Do I need a paid Claude plan to build custom skills?
No. Building and testing custom skills locally in Claude Code works on free and Pro accounts alike. Publishing to a shared organization workspace through the Skills API requires a Claude Platform account with workspace admin access.
What’s the difference between a Skill and a plugin?
A Skill is a written operating procedure defined by a SKILL.md contract — instructions plus optional supporting files. A plugin is a packaging and distribution layer that can bundle one or more skills together for easier installation; the skill format itself stayed unchanged when the Skills API reached general availability, precisely so it wouldn’t get tangled up with any one distribution mechanism.
Can a skill call external APIs or run arbitrary code?
A skill’s instructions can direct Claude to run supporting scripts bundled in the same folder, and those scripts can make network calls or run other code, subject to the same permissions and sandboxing that apply to any tool use in your Claude Code session.
How many skills can I have in one project?
Anthropic’s public documentation doesn’t state a hard numeric cap. In practice, keep the number manageable enough that each skill’s description stays specific — a project with dozens of overlapping, vaguely-worded skills will see worse invocation accuracy than one with a handful of narrowly scoped ones.
Do skills work the same way in the Claude Agent SDK as in Claude Code?
The underlying contract is identical — a filesystem artifact with a SKILL.md file — but in the Agent SDK you explicitly configure your agent to load skills from a given directory, rather than relying on the CLI’s automatic project-root discovery.
Can I share a skill publicly the way I’d share an open-source library?
Yes. Anthropic’s own public skills repository on GitHub is one example, and the community-run Awesome Claude Skills directory catalogs skills published by individual developers, installable via plugin commands that place them at the standard discovery path.
My skill’s instructions are long. Will that slow Claude down?
Skills load on demand rather than being preloaded into every conversation, which is the entire point of progressive disclosure. That said, once loaded, lengthy instructions do consume context budget like any other text Claude reads, so keeping instructions focused is still good practice even though it isn’t strictly required.
What happens if two skills have overlapping descriptions?
Claude picks based on the closest match to the conversation’s context, but overlapping descriptions increase the odds of the wrong skill firing. If you notice this happening, the fix is almost always to narrow both descriptions until their trigger conditions no longer overlap.
Related Coverage
- Build an AI Image Generator API: 13 Steps, 90 Min [2026]
- Build a Self-Hosted Text-to-Speech API: 12 Steps [2026]
- How to Use Qwen-Image-3.0: 12 Steps, 90 Min [2026]
- How to Use Google AlphaEvolve: 12 Steps, 90 Min [2026]
- How to Use Leonardo AI Image Generator: 12 Steps [2026]
