Claude Skills Explained: What They Are, How They Work, and How to Use Them Safely

Claude Skills are folders of instructions, scripts, and reference files that Claude loads on demand to perform a specific task the way you want it done - instead of you re-explaining your process, your formatting rules, or your internal conventions in every single conversation. If you've searched "claude skills" wondering what Claude Skills actually are, how they're different from a plugin or an MCP server, or whether it's safe to install a Claude Skill someone else built, this guide covers all of it in one place.

We're covering Claude Skills here because two parts of it touch what we actually build at Scanverra: the security hygiene of scripts a Claude Skill runs (Scanverra's Repo Scanner catches leaked API keys, including Anthropic's), and whether a website is structured in a way that Claude and other AI agents can actually read it. Where that overlap is real, we'll say so - and where it isn't, we won't pretend otherwise.

What Are Claude Skills?

Claude Skills, in one sentence: a Claude Skill is a folder of instructions (and optionally scripts or reference files) that Claude loads only when a task calls for it, so a team can teach Claude a repeatable process once instead of re-explaining it in every conversation.

Claude Skills are a packaging format Anthropic built so Claude can extend its own capabilities at runtime. A Claude Skill is a folder containing a SKILL.md file - plain-language instructions describing what the skill does and when to use it - plus, optionally, helper scripts, templates, or reference documents the skill can call on. Claude reads the short description of every available Claude Skill up front, and only loads the full SKILL.md content (and any bundled files) into context when a task actually needs that particular skill. Anthropic calls this "progressive disclosure," and it's the core design idea behind Claude Skills: capability without a constant context-window tax.

In practice, a Claude Skill can teach Claude your company's slide-deck format, how your team writes commit messages, how to fill out a specific spreadsheet template, or how to run a multi-step data-processing script - anything repeatable enough to be worth encoding into a Claude Skill once rather than re-explaining every time.

Claude Skills at a Glance
Format	SKILL.md instructions + optional scripts, templates, and reference files
Where Claude Skills run	Claude apps, Claude Code, the Claude Agent SDK, and the API
Where to find Claude Skills	Anthropic's own skills directory and community repos on GitHub
Related but different	MCP (live server connections) and single-function tools
Main risk to manage	Hardcoded credentials in a skill's bundled scripts, and unreviewed code-execution access

How Do Claude Skills Work?

The Anatomy of a Claude Skill

Every Claude Skill - regardless of which surface a given Claude Skill runs on - starts with a SKILL.md file with a short YAML header (name and a one- or two-sentence description) followed by the actual instructions in Markdown. That description is what Claude scans to decide whether a given Claude Skill is relevant to the task at hand - so a well-written Claude Skill front-loads the specific triggers ("use this when the user asks for a PDF report," for example) rather than a vague summary. Beyond SKILL.md, a Claude Skill folder can include:

• Scripts - Python, JavaScript, or shell scripts a Claude Skill can execute for deterministic, repeatable steps (parsing a file format, calling an internal API, running a calculation) rather than asking Claude to reason through every step in natural language.
• Reference files - style guides, schemas, sample outputs, or documentation Claude can read into context only when that Claude Skill is actually invoked.
• Templates - boilerplate documents, code scaffolding, or configuration files a Claude Skill fills in or modifies.

This structure is what separates Claude Skills from just pasting a long system prompt into every conversation: the instructions and supporting files stay dormant, in storage, until the specific Claude Skill is triggered, keeping unrelated conversations fast and cheap.

Where Claude Skills Run

Claude Skills work across the surfaces Anthropic ships Claude on: in Claude apps (web, desktop, mobile) as personal or team-shared Claude Skills, in Claude Code for developer workflows, and through the Claude Agent SDK and API for teams building their own custom agents with Claude Skills on top of Claude. The mechanics are consistent everywhere - Claude sees a list of available Claude Skills by name and description, decides which one (if any) applies, and loads it - but the trust boundary is different depending on where the Claude Skill is running. A Claude Skill running in Claude Code or the Agent SDK, with code execution enabled, can read and write files and run scripts on a real machine, which is exactly why the security section below matters.

Claude Skills vs. MCP and Custom Tools

It's easy to conflate Claude Skills with the Model Context Protocol (MCP), since both extend what Claude can do, but they solve different problems. MCP is a protocol for connecting Claude to external systems and live data - a database, a ticketing system, a company's internal API - through a standing server connection. A Claude Skill, by contrast, is a packaged set of instructions and static resources bundled with the conversation or agent environment itself; a Claude Skill doesn't require running a server. A useful rule of thumb: reach for MCP when Claude needs to talk to a live external system, and reach for a Claude Skill when you need Claude to reliably follow a specific process or produce output in a specific format. The two aren't mutually exclusive - a Claude Skill's bundled script can absolutely call out to an MCP-connected service - but a Claude Skill and an MCP server are solving different halves of the same "make Claude work the way my team works" problem.

The Claude Skills Marketplace and Directory

A growing ecosystem sits around Claude Skills themselves - official listings, community repos, and internal company libraries of Claude Skills built for one team's specific workflows.

Finding Claude Skills Built by Others

Anthropic and the broader Claude Skills community publish example and production-ready Claude Skills on GitHub, and Anthropic's own skills directory surfaces vetted, first-party Claude Skills for common jobs - document creation, spreadsheet work, presentation generation, and more. Before installing a third-party Claude Skill from a marketplace listing or a GitHub repo, read the actual SKILL.md and any bundled scripts the same way you'd review a pull request: a Claude Skill with code-execution access runs with real file-system and network permissions, so "it's popular on the marketplace" isn't the same guarantee as "I read what it does."

Building Your Own Custom Claude Skill

Writing a custom Claude Skill starts with identifying a task you or your team repeats often enough that re-explaining it every time is wasted effort - a recurring report format, a data-cleaning routine, a specific coding convention. From there: write a clear, specific SKILL.md description (this is what determines whether Claude actually picks the right Claude Skill up at the right moment), keep the Claude Skill scoped to that one job rather than turning it into a catch-all, and test the Claude Skill against edge cases before rolling it out to a whole team. If your Claude Skill includes a script that calls an external API, that's exactly where the next section applies.

Claude Skills Security: What to Check Before You Build or Install One

The most common real-world mistake with a custom Claude Skill isn't exotic - it's a script inside the Claude Skill's folder with an API key typed directly into the source instead of pulled from an environment variable, then committed to a shared or public repo. This isn't specific to Claude Skills; it's the same hardcoded-secret mistake that shows up in application code generally. But because a Claude Skill's scripts are often written quickly, shared informally between teammates, and sometimes published to a public marketplace, the odds of a stray key slipping through go up. If the script calls the Claude API directly, the credential at risk is your Anthropic API key - and a leaked API key gets used for unauthorized usage on your account the moment it's found, not eventually.

This is a case where we can point to something concrete: Scanverra's Repo Scanner runs secret-detection rules across a connected repository, and one of those rules specifically matches the Anthropic API key format (sk-ant-...) as a critical-severity finding - the same class of check it runs for AWS, Stripe, GitHub, and other provider key formats. If your team is building or storing custom Claude Skills in a shared repo, running a secrets scan over that repo is the same due diligence you'd apply to any other codebase, not a Claude-specific extra step. For the underlying mechanics of how this happens and how to clean it up if it already has, see how secrets end up in git history and how to fix hardcoded secrets in your codebase.

Making Sure Claude Can Actually Find and Read Your Website

There's a second, less obvious way the "Claude Skills" topic connects to what we build, even though it's a separate question from Claude Skills themselves: Claude, like other AI systems, can browse and read live web pages when a task calls for it, and whether your site is structured for that kind of access matters just as much as which Claude Skills your team has installed. Two things determine it - whether your robots.txt allows AI crawlers in the first place, and whether the page itself is easy for a model to parse once it gets there.

robots.txt and AI Crawlers

Anthropic's crawler (along with GPTBot, CCBot, and others) respects standard robots.txt directives. A surprising number of sites block these crawlers by accident - often a blanket disallow rule copied from a template years before AI crawlers existed - which means Claude and similar tools simply can't see that content when asked about it. We cover the mechanics in full in our robots.txt and sitemap.xml guide, and the fix itself in how to fix robots.txt blocking AI crawlers.

Structured Data and Semantic Markup

Beyond access, clear JSON-LD structured data and semantic HTML (a real <main> landmark, proper heading hierarchy) make it easier for any AI system, Claude included, to understand what a page is actually about rather than guessing from raw DOM structure - see structured data and AI search for the specifics. Scanverra's website audit checks robots.txt access, structured data, and semantic landmarks as part of a full report - none of which requires Claude Skills to be involved at all, since this is about page structure, not the Claude Skills a visitor's Claude might be running. We're candid that the newer "agentic browsing" checks specifically are still an early, actively-developed part of that report rather than a finished, mature feature - it's useful today as a directional signal, not a certified score.

Real-World Use Cases for Claude Skills

The clearest Claude Skills use cases share one trait: a task done the same way, often enough, that documenting it once as a Claude Skill beats re-explaining it every session.

• Document and report generation - a Claude Skill that knows your team's slide template, report structure, or brand voice and applies it consistently.
• Developer workflows in Claude Code - a Claude Skill encoding your team's PR checklist, commit-message format, or test-writing conventions.
• Data processing - a Claude Skill bundling a script that parses a specific file format or internal data structure your team works with regularly.
• Customer-facing agents built on the Agent SDK - Claude Skills that encode a specific support workflow or escalation path so the agent behaves consistently across sessions.

Claude Skills Best Practices Checklist

Whether you're installing someone else's Claude Skill or writing your own, this checklist covers the habits that separate a well-run Claude Skills setup from one that quietly accumulates risk:

• Write a specific, trigger-focused SKILL.md description rather than a vague one, so Claude picks the right Claude Skill up at the right moment.
• Keep each Claude Skill scoped to one job - a catch-all Claude Skill is harder to review, test, and trust.
• Never hardcode API keys, tokens, or credentials in a Claude Skill's bundled scripts - use environment variables, and scan the repo if you're not certain none slipped through.
• Read the full contents of any third-party Claude Skill from a marketplace or GitHub before granting that Claude Skill code-execution access.
• Test a new Claude Skill against edge cases, not just the happy path, before rolling it out to a full team.
• Version and review changes to shared Claude Skills the same way you'd review a code change - a Claude Skill runs with real permissions once enabled.

Claude Skills are a genuinely useful way to make Claude behave consistently around your team's specific processes instead of re-explaining them every session - the Claude Skills format itself (a SKILL.md file plus optional scripts and resources) is simple by design. The parts worth real care are the same as with any code you'd run or share: keep secrets out of the scripts a Claude Skill bundles, and read what a Claude Skill actually does before you trust it with file or network access. If you're building or maintaining Claude Skills in a shared repository, running a secrets and dependency check over that repo periodically is a small piece of upkeep that catches the mistake before it ships. Scanverra's Repo Scanner is one straightforward way to do that, and our website audit covers the AI-crawler and structured-data side if you're also trying to make your own content easier for Claude to read once your Claude Skills themselves are in good shape.