The era of starting every AI conversation from scratch is officially over. If you find yourself constantly re-explaining your coding preferences, your company’s brand guidelines, or your multi-step workflows to your AI assistant, you are losing valuable time. Meet Claude Skills, a revolutionary feature by Anthropic that allows you to teach your AI exactly how you work, saving those instructions as a reusable, automated capability.
Think of agent skills as instruction manuals for AI agents. Instead of hoping the AI guesses your workflow correctly, skills provide a structured, predictable path to success.
Whether you are a non-technical user looking to automate emails or a senior developer orchestrating multiple Model Context Protocol (MCP) servers, this comprehensive guide will show you how to build custom Claude Skills with zero sweat.
Key Takeaways
- Claude Skills are reusable instruction folders that standardize how your AI performs specific tasks across different platforms.
- The system uses Progressive Disclosure, loading metadata, instructions, and reference files only when necessary to optimize performance.
- Skills are based on the open standard agentskills.io, ensuring portability between Claude, Cursor, VS Code, and other developer tools.
- You can create skills manually via SKILL.md files, through the Claude web interface, or by synthesizing complex documentation using tools like NotebookLM.
What Exactly Are Claude Skills?
At their core, Claude Skills are reusable instructions packaged as a simple folder. When your AI agent starts up, it reads these folders to understand what specialized knowledge or workflows it has access to.
What makes this system truly groundbreaking is that it relies on an open standard (agentskills.io). This means a skill you build today is incredibly portable; it will work seamlessly across the Claude web app, Claude Code, and third-party tools like Cursor, VS Code, Goose, Letta, and Gemini CLI. You write the skill once, and your AI assistant knows how to do its job everywhere.
Skills utilize a brilliant concept called Progressive Disclosure. Instead of overwhelming the AI by loading thousands of instructions into its memory at once, skills operate on a three-level system:
- First Level (YAML Frontmatter): This sits at the top of the file and contains basic metadata. It is always loaded in the AI’s system prompt and provides just enough information for Claude to know when a skill should be triggered without reading the whole file.
- Second Level (The Markdown Body): If the AI decides the skill is needed based on the frontmatter, it loads the main instructions.
- Third Level (Linked Resources): If your skill requires external files (like a 50-page style guide), the AI can choose to navigate and open those bundled reference files only when explicitly needed.
The Anatomy of a Perfect SKILL.md File
Creating a skill does not require advanced programming. A basic skill is simply a folder containing a single text file named exactly SKILL.md (this is case-sensitive). If you want to build a more complex workflow, your skill folder can be expanded to include:
- SKILL.md: The mandatory main instruction file.
- scripts/: A folder for executable code, such as Python or Bash scripts.
- references/: A folder for long documentation or API guides.
- assets/: A folder for templates, fonts, or icons that the AI might need.
The most critical part of the SKILL.md file is the YAML Frontmatter. This sits at the very top of the document between three dashes (—). It must contain a name and a description. Strict Frontmatter Rules You Must Follow:
- Name: Must be formatted in kebab-case (e.g., my-cool-skill), contain no spaces, and no capital letters.
- Description: Must explain what the skill does and exactly when to use it.
- Security Restrictions: Never include XML angle brackets (< or >) in your frontmatter.
Three Ways to Create a SKILL.md File
You don’t have to be a programmer to create a Claude Skill. At its simplest, a Skill is a small package of instructions that teaches Claude how you want a particular task to be performed.
There are three practical ways to create one. The best method depends on how much control you want and how complicated the workflow is.
If you are completely new to Skills, start with Method 1. If you want to understand exactly what Claude is being instructed to do, use Method 2. And if your Skill needs to learn from a large collection of documents, Method 3 can save you a great deal of research time.
Method 1: Let Claude Create the Skill for You
Best for: beginners, non-technical users, and anyone who wants to create a Skill quickly.
This is the easiest approach because you don’t have to start by learning YAML, Markdown syntax, folder structures or other technical details. You simply explain the workflow you want Claude to learn, and Claude helps turn that description into a Skill.
Anthropic’s current Claude interface allows users to create and upload custom Skills through Customize > Skills. Claude’s documentation also recommends starting simple, using clear descriptions, including examples where useful, and testing the Skill with different prompts.
Step 1: Decide what you want Claude to learn
Before opening the Skill creator, describe the task in plain English.
For example, don’t think:
“I need a YAML frontmatter configuration with conditional instructions.”
Instead, think:
“I want Claude to turn my rough blog ideas into SEO-friendly articles using my preferred structure and writing style.”
That is enough to get started.
A good Skill should normally solve one specific, repeatable problem. For example:
- Turn meeting notes into professional minutes.
- Convert research into blog articles.
- Review resumes using a particular checklist.
- Create social media posts in a company’s brand voice.
- Analyze financial reports using a fixed process.
- Turn a product brief into a standard marketing document.
The more focused the task, the easier it is for Claude to follow the Skill consistently.
Step 2: Explain the workflow
Tell Claude what should happen from beginning to end.
For example:
“When I give you a rough article idea, first identify the target audience, then create an outline, research missing information, write the article, add SEO elements, and finally check the article against my checklist.”
Notice that you are not writing code. You are simply explaining how you normally do the job.
You can also tell Claude what the final result should look like:
“Use H2 headings, short paragraphs, examples, a conversational tone and a conclusion. Avoid unnecessary jargon.”
These instructions eventually become the core of your Skill.
Step 3: Give Claude examples
Examples are extremely useful because they show Claude what “good” looks like.
For instance, if you’re creating a Skill for writing product descriptions, provide Claude with:
- One example you consider excellent.
- One example you consider poor.
- Your preferred tone.
- Words or phrases you want to avoid.
- The structure you normally follow.
Instead of saying only:
“Write product descriptions professionally.”
you can say:
“Start with a one-sentence benefit, followed by three key features, then explain who the product is for. Keep the description between 100 and 150 words. Avoid exaggerated claims.”
The second instruction leaves much less room for interpretation.
Step 4: Ask Claude to build and explain the Skill
Once you’ve described the workflow, ask Claude to create the Skill package.
A useful prompt is:
“Create a Claude Skill for this workflow. Include the required SKILL.md file, clear instructions for when the Skill should be used, the step-by-step workflow, examples, and any supporting files that would be useful. Keep the Skill focused on this one task.”
Claude can then help generate the contents of SKILL.md and, when necessary, supporting resources.
A basic Skill requires a skill.md file containing name and description metadata. Anthropic currently specifies a maximum of 64 characters for the name and 200 characters for the description.
Step 5: Test it with a real request
Don’t assume that a Skill works simply because the file looks correct.
Give Claude a real example.
For an article-writing Skill, you might provide:
“Write an article about how small businesses can use AI for customer service.”
Then examine the result.
Ask yourself:
- Did Claude follow the desired structure?
- Did it use the correct tone?
- Did it perform the steps in the right order?
- Did it follow the rules?
- Did it produce the format I expected?
If something is wrong, tell Claude what needs to change and refine the Skill.
Why this method is useful
The biggest advantage is simplicity. You concentrate on describing your expertise and workflow rather than worrying about file formatting.
It is particularly useful for someone who has never created a Skill before.
Think of it this way:
You explain the job → Claude turns your explanation into instructions → you test the result → you refine it.
That is often all you need for a useful first Skill.
Method 2: Create the SKILL.md File Manually
Best for: users who want maximum control, developers, advanced users, and anyone building reusable Skills for a team.
The second method is more hands-on. Instead of asking Claude to create the Skill package for you, you create the folder and write the SKILL.md file yourself.
Don’t let the word “manual” scare you. You don’t need to be a software engineer. A basic Skill is essentially a text document containing instructions.
The important thing is understanding what each part of that document does.
Step 1: Create the Skill folder
Start with a folder whose name identifies your Skill.
For example:
blog-writer/
Inside it, create:
blog-writer/
└── SKILL.md
The SKILL.md file is the heart of the Skill.
If your Skill becomes more sophisticated, you can add other folders:
blog-writer/
├── SKILL.md
├── references/
├── scripts/
└── assets/
You don’t need all of these.
A beginner can start with just SKILL.md and add supporting files later. Anthropic recommends starting simple and expanding a Skill when additional resources or executable scripts are genuinely useful.
Step 2: Write the Skill’s identity
At the beginning of SKILL.md, define the Skill’s name and description.
For example:
---
name: blog-writer
description: Turn rough ideas and research into structured, SEO-friendly blog articles using a consistent editorial style.
---
Think of the description as the Skill’s elevator pitch. It should answer two questions: What does this Skill do? and When should Claude use it?
This is particularly important because Claude uses the description as part of deciding when a Skill is relevant. Anthropic specifically identifies the description as critical to Skill invocation.
Step 3: Tell Claude exactly what to do
After the frontmatter, write the actual instructions.
For example:
## Instructions
When the user provides a topic for a blog article:
1. Identify the intended audience.
2. Identify the main search intent.
3. Create a logical outline.
4. Research factual claims when necessary.
5. Write the article using short paragraphs.
6. Use descriptive H2 and H3 headings.
7. Include examples where they improve understanding.
8. End with a concise conclusion.
9. Check the article for factual consistency before presenting it.
This is where your expertise goes. Imagine that Claude is a new employee who has never done the job before. Your SKILL.md is the training manual you give that employee. If there are rules that the employee must always follow, put those rules in the Skill.
Step 4: Add examples
Examples can make the Skill considerably more reliable.
You could add:
## Example
Input:
Write an article explaining AI automation to small business owners.
Expected approach:
- Assume the reader is non-technical.
- Explain technical terms in plain English.
- Use practical business examples.
- Avoid unnecessary programming terminology.
- Structure the article with clear subheadings.
The goal isn’t to fill the Skill with dozens of examples. It is to give Claude enough examples to understand what successful execution looks like.
Step 5: Add reference files only when necessary
Suppose you’re creating a Skill for a company’s brand guidelines.
Instead of putting 50 pages of brand documentation into SKILL.md, you could create:
brand-skill/
├── SKILL.md
└── references/
├── brand-guidelines.md
├── approved-terminology.md
└── editorial-rules.md
Then SKILL.md can tell Claude when those files should be consulted. This keeps the main Skill instructions relatively focused while allowing the Skill to draw on much larger bodies of information when necessary. Anthropic recommends adding reference files when a Skill contains information that is too large or scenario-specific for the main file.
Step 6: Add scripts only when a task requires them
Some Skills need to do more than provide instructions.
For example, imagine you create a Skill that processes a spreadsheet containing 50,000 rows of sales data. A Python script could perform calculations or transform the data much more reliably than asking Claude to manually process everything.
Your Skill could therefore contain:
data-analysis/
├── SKILL.md
└── scripts/
└── analyze_sales.py
The SKILL.md explains when and how the script should be used, while the script performs the actual computation.
Anthropic’s documentation supports executable code such as Python and JavaScript inside Skills, although dependencies and the execution environment need to be considered.
The important rule: don’t over-engineer your first Skill
A common mistake is to immediately create a huge Skill containing dozens of files, scripts and complicated instructions.
Start with:
my-skill/
└── SKILL.md
Get that working first. Then ask: “What does Claude still need that isn’t already in this file?”
- If the answer is “a large reference document,” add
references/. - If the answer is “a repeatable calculation or file-processing operation,” consider
scripts/. - If the answer is “nothing,” stop there.
- A simple Skill that works reliably is much better than a complicated Skill that is difficult to maintain.
Method 3: Use NotebookLM to Turn Documentation into a Skill
Best for: documentation-heavy Skills, company policies, technical manuals, research workflows, API documentation and other information-rich tasks.
Sometimes the hardest part of creating a Skill isn’t writing the instructions. It’s figuring out what the instructions should be.
Imagine you want to create a Skill that teaches Claude how to follow your company’s 150-page editorial handbook. You could read the entire handbook, identify the important rules, summarize them, determine which rules apply in which situations, and then write the SKILL.md yourself.
Or you can use a research tool such as Google NotebookLM to help extract the important information first. The key distinction is that NotebookLM is best used here as a research assistant, not as the final Skill-building environment.
Step 1: Gather the source material
Start by collecting the documents that describe the process you want Claude to follow.
These might include:
- PDF manuals
- Company policies
- Training documents
- Product documentation
- API documentation
- Standard operating procedures
- Research papers
- Internal guidelines
- Existing process documents
- Frequently asked questions
Upload the relevant material into NotebookLM.
For example, if you’re creating a Skill for customer-support responses, you might upload:
Customer Support Skill
├── Customer service handbook.pdf
├── Refund policy.pdf
├── Product FAQ.pdf
├── Tone of voice guide.pdf
└── Escalation procedure.pdf
Step 2: Ask NotebookLM to find the rules
Don’t simply ask:
“Summarize these documents.”
A summary is not necessarily a good Skill.
Instead, ask questions that extract repeatable instructions.
For example:
“Identify every rule that a customer-support agent must follow when responding to customers.”
Then:
“Which rules are mandatory and which are optional?”
Then:
“What situations require escalation to a human?”
Then:
“Create a decision tree showing what the agent should do in each situation.”
Then:
“List the common mistakes an agent must avoid.”
These questions turn a pile of documents into something much more useful: a workflow.
Step 3: Separate facts from actions
This is one of the most important steps. A Skill isn’t simply a knowledge dump. Consider the difference between these two statements:
Knowledge:
“Our refund period is 30 days.”
Instruction:
“When a customer requests a refund, first check whether the purchase falls within the 30-day refund period. If it does, follow the standard refund procedure. If it does not, explain the policy and escalate if an exception may apply.”
The first statement gives Claude information. The second tells Claude what to do with that information. A good Skill needs both when appropriate—but the instructions are what turn reference material into a workflow.
Step 4: Ask NotebookLM to identify edge cases
Real-world processes rarely consist of simple “if this, do that” rules.
Ask questions such as:
- “What exceptions are mentioned in the documentation?”
- “Are there situations where the normal process does not apply?”
- “What decisions require human approval?”
- “What information must never be disclosed?”
- “What are the most common mistakes someone following this process could make?”
These answers can become valuable sections of your SKILL.md.
Step 5: Bring the distilled information into Claude
Once you have extracted the important rules, give them to Claude and ask it to turn them into a Skill.
For example:
“Using the workflow, rules, exceptions and decision points below, create a Claude Skill. Write a concise SKILL.md with clear metadata, instructions, examples, decision rules and references to supporting documentation.”
Claude can then organize the material into the actual Skill structure. This approach is particularly useful when you’re dealing with hundreds of pages of source material because you don’t have to manually search through every document before you begin designing the workflow.
Step 6: Validate the Skill against the original documents
This final step is essential. Never assume that a generated Skill is correct simply because the source documents were correct. Take important rules from the original documentation and test the Skill against them.
For example:
Source rule: Customers can request refunds within 30 days except for Product X.
Now test:
“A customer bought Product X 10 days ago and wants a refund. What should you do?”
Then test an edge case:
“A customer bought Product Y 45 days ago and claims the product was defective. What should you do?”
The objective is to determine whether your Skill has correctly captured both the normal rule and the exception.
Why this method is useful
NotebookLM is particularly valuable when the Skill is based on information that already exists somewhere else.
Instead of asking:
“What should my Skill say?”
you are effectively asking:
“What are the important rules hidden inside these documents, and how can I turn those rules into a repeatable workflow?”
That makes this method especially powerful for companies and professionals who already have extensive documentation but don’t know how to convert it into instructions an AI can reliably follow.
Which Method Should You Choose?
You don’t need to choose the most technical method simply because it sounds more advanced.
Use the method that matches your situation.
| Your situation | Best method |
|---|---|
| “I’ve never created a Skill before.” | Method 1: Let Claude create it |
| “I know exactly how I want the workflow to work.” | Method 2: Write it manually |
| “My workflow is based on lots of documents.” | Method 3: NotebookLM + Claude |
| “I want complete control over every instruction.” | Method 2 |
| “I have company manuals, policies or SOPs.” | Method 3 |
| “I just want something working quickly.” | Method 1 |
There is also nothing stopping you from combining the methods. For example, you could use NotebookLM to analyze 200 pages of company documentation, use Claude to turn the findings into a first draft, and then manually edit the SKILL.md to add your own rules.
In practice, that combination can be one of the most effective approaches.
How to Deploy and Share Your Skills
Creating a SKILL.md file is only half the job. Once your Skill is ready, you need to get it into Claude and, if necessary, make it available to other people.
The best deployment method depends on whether you are using the Skill personally, sharing it with a small team, publishing it publicly, or connecting it to an automated application.
Here are the main ways to distribute a Claude Skill.
1. ZIP File Method: The Simplest Way to Share a Skill
Best for: individual users, beginners, testing, and sharing a Skill with another person.
The easiest way to distribute a Skill is to package its folder into a ZIP file.
For example, if your Skill looks like this:
blog-writer/
├── SKILL.md
├── references/
│ └── writing-guide.md
└── assets/
└── template.docx
you can package the entire blog-writer folder into:
blog-writer.zip
The important point is that the ZIP should contain the Skill folder itself, with SKILL.md inside it, rather than placing SKILL.md directly at the root of the ZIP. Anthropic’s current documentation specifies that the Skill folder should be the ZIP’s top-level entry.
Once you have the ZIP, Claude users can go to Customize → Skills → + → Create skill → Upload a skill and upload the file. The Skill will then appear in their Skills list and can be enabled when needed.
This method is particularly useful when you have created a Skill for yourself and want to give the same Skill to a colleague.
Think of it like this:
SKILL.md + supporting files → ZIP → Upload to Claude → Enable Skill
No server, GitHub repository or programming is required.
One thing to remember is that a Skill uploaded to an individual account is normally private to that account. If you want to distribute it officially across a Team or Enterprise organization, use the organization-level options described below.
2. Organization-Wide Deployment: Give Your Team the Same Skill
Best for: companies, agencies, departments and Enterprise or Team users.
If you have created a Skill that should be used by an entire team, asking every employee to download and upload the same ZIP file isn’t ideal.
For example, imagine a company creates a Skill called:
company-brand-guidelines
It teaches Claude how to use the company’s approved terminology, tone, colors, formatting and messaging. Instead of asking 100 employees to install it individually, an organization owner can provision the Skill centrally.
On Team and Enterprise plans, organization owners can upload a Skill through Organization settings → Skills. Once provisioned, the Skill becomes available to users across the organization.
This is especially useful for standardized workflows such as:
- Company brand guidelines
- Legal document templates
- HR procedures
- Sales proposal generation
- Financial reporting
- Customer-support workflows
- Internal research procedures
- Compliance processes
Organizations can also share Skills with specific colleagues or publish them to the organization’s Skill directory, depending on the sharing settings enabled by the administrator.
Why centralized deployment matters
Imagine your marketing department has a Skill that tells Claude exactly how to write company announcements.
If the Skill is updated from:
“Use the old company tagline”
to:
“Use the new company tagline”
you don’t want every employee maintaining a different copy. With centralized deployment, the organization can maintain an approved version and distribute updates from one place.
For specialized Skills, organizations can also use plugins to bundle Skills and assign them to particular groups. For example, a collection of ten marketing Skills could be made available only to the marketing team rather than the entire company.
3. GitHub: Best for Version Control and Open-Source Skills
Best for: developers, open-source projects, teams that frequently update Skills, and collaborative development.
If you’re treating your Skill like a real software project, GitHub can be a better home than a ZIP file. A Skill is essentially a collection of files, which makes it well suited to version control.
For example:
github.com/yourname/seo-writing-skill
could contain:
seo-writing-skill/
├── SKILL.md
├── references/
│ ├── seo-guide.md
│ └── editorial-rules.md
├── scripts/
│ └── keyword-checker.py
└── README.md
You can then track changes over time.
For example:
- Version 1.0
Basic SEO writing instructions. - Version 1.1
Added title and meta-description rules. - Version 1.2
Added a keyword-analysis script. - Version 2.0
Completely redesigned the workflow.
This makes GitHub particularly useful when several people are working on the same Skill.
Anthropic also supports GitHub-synced marketplaces for organizational plugins, allowing teams to manage plugin packages through a version-controlled repository and have updates synchronized.
Why GitHub is useful
A ZIP file is essentially a snapshot. GitHub gives you a history.
You can see:
- Who changed the Skill
- What was changed
- When it was changed
- Which version worked better
- What changed between two versions
It also makes collaboration much easier. For open-source Skills, GitHub can additionally become the public home where other people can inspect, improve, fork and contribute to the project.
4. Plugins: Package Multiple Skills Together
Best for: teams that need an entire collection of related Skills rather than one Skill.
As your Skill library grows, you may eventually discover that you don’t have just one Skill—you have dozens.
For example, a marketing department might have:
Marketing Plugin
├── blog-writing
├── social-media
├── email-copywriting
├── brand-guidelines
├── competitor-analysis
└── campaign-reporting
Installing each Skill separately becomes inconvenient.
A Claude plugin can bundle Skills together, along with other components such as connectors and sub-agents, to create a ready-to-use package for a particular role or department. This makes plugins particularly useful for organizations.
Instead of telling a new marketing employee:
“Install these six Skills, connect these three services and configure these settings.”
the organization can provide a marketing plugin that brings the required capabilities together.
For example:
Marketing Plugin → Skills + Connectors + other workflow components
This is more scalable than distributing individual Skills one at a time.
5. Programmatic API Integration: Use Skills Inside Your Own Applications
Best for: developers building automated systems, AI agents, SaaS products and internal applications.
The final method is for people who aren’t simply using Claude through the website. Suppose you’ve built your own application that uses the Claude API. You might want Claude to automatically use your custom Skill whenever a particular workflow runs.
For example:
Customer submits request
↓
Your application
↓
Claude API
↓
Customer-support Skill
↓
Claude generates response
↓
Your application sends response
Anthropic provides a Skills API for uploading and managing custom Skills, and Skills can then be supplied to the Messages API through the container parameter. For example, a developer could create a Skill for financial analysis and then combine it with Anthropic’s spreadsheet Skill in an automated workflow.
The application could effectively tell Claude:
“Use the Excel Skill to work with the spreadsheet and use my financial-analysis Skill to apply our company’s valuation methodology.”
Multiple Skills can be used together in a single API request, with Anthropic currently documenting support for up to eight Skills per request.
Why this is powerful
This moves Skills beyond personal Claude usage.
Instead of a human saying:
“Claude, please use my financial-analysis Skill.”
your software can automatically provide the appropriate Skill whenever the workflow requires it.
For production applications, Anthropic also supports Skill versioning, allowing developers to pin an application to a specific version rather than automatically using the newest version. This is useful when you need predictable behavior after deployment.
One important distinction
The API route is not simply “upload a SKILL.md and call /v1/skills.”
The current API documentation describes Skills as being managed through the Skills API and then supplied to the Messages API through the container.skills configuration. So, if you’re writing this article for a current audience, it is better to describe this as:
“Programmatic deployment through Anthropic’s Skills API”
rather than telling readers to manually inject Skills through a /v1/skills endpoint.
Which Deployment Method Should You Use?
You don’t need GitHub or the API just because they sound more advanced.
Choose based on what you’re trying to accomplish:
| Situation | Recommended method |
|---|---|
| I want to use my Skill myself | ZIP upload |
| I want to send a Skill to a colleague | ZIP upload / Skill sharing |
| I want my whole company to use it | Organization-wide deployment |
| I want different Skills for different departments | Plugins / group deployment |
| I want to collaborate with developers | GitHub |
| I want to publish an open-source Skill | GitHub |
| I want several Skills bundled together | Plugin |
| I want Claude to use the Skill inside my own application | Skills API |
| I need controlled versions for production | Skills API + versioning |
The important thing is to start simple.
For most individual users, a ZIP file is enough. For a company, centralized organization deployment or plugins make more sense. And if you’re building an automated application around Claude, the Skills API is the natural next step.
In other words:
- Personal use → ZIP
- Team use → Organization sharing
- Large-scale team workflows → Plugins
- Open-source collaboration → GitHub
- Software and automation → API
Join our community by subscribing to our Weekly Newsletter to stay updated on the latest AI updates and technologies, including the tips and how-to guides.
Also, follow us on Instagram (@tid_technology) for more updates in your feed and our WhatsApp Channel to get daily news straight to your Messaging App.
