> ## Content Index
> Fetch the complete content index at: https://jonathancanales.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# Claude Skills: what they are and how to create one from scratch
- URL: https://jonathancanales.com/en/claude-skills-what-they-are-how-to-create/
- Published: 2026-07-13T14:00:00.000Z
- Updated: 2026-10-25T18:02:47.000Z
- Description: A guide to Claude Skills: what they are, where they work, which procedures to convert, and how to create the first one step by step.
- Author: Jonathan Canales
- Tags: #en, Technology and tools

Claude Skills are among the most practical ideas Anthropic has introduced in its ecosystem: packages of instructions, resources, and code that teach Claude to do a specific task your way, over and over, with the same quality. Instead of repeating the same long prompt every week, you store the procedure once and Claude applies it whenever it detects the task calls for it.

Anthropic introduced Agent Skills in October 2025, and they have since become a core piece of Claude.ai, Claude Code, and the Agent SDK for developers. This guide explains what they are exactly, how they work inside, and how to create your first skill from scratch, with a complete example you can adapt today.

![Doodle of spiral recipe cards with an orange bookmark ribbon](https://jonathancanales.com/content/images/2026/10/p4-doodle1-2.png)

## What a Claude skill is

A skill is a folder with a main file called SKILL.md plus, optionally, supporting files: templates, scripts, reference documents, or examples. The SKILL.md file starts with a YAML header holding two key fields: name, the skill identifier, and description, a short explanation of what it does and when it should be used. Below the header go the full instructions in markdown.

The underlying idea is simple: the instructions you repeat in every conversation today move into a file that is versionable, shareable, and improvable. A team can maintain one skill for weekly reports in their exact format, another for code reviews with their conventions, and another for sales proposals with their template. Each skill encapsulates a complete procedure, quality criteria included.

Anthropic also published the format specification as an open standard in late 2025, so other tools can adopt the same format and skills can travel between compatible products.

## How it works inside: progressive disclosure

The smartest design decision in skills is how they consume context. Claude works with a limited context window, and filling it with the full manuals of every procedure would be a waste. Skills solve this with progressive disclosure across three levels.

At the first level, Claude only loads the name and description of each available skill. That is a few words per skill, enough to decide whether the current task relates to any of them. At the second level, when a skill turns out relevant, Claude reads the full body of the SKILL.md and follows its instructions. At the third level, if the SKILL.md references additional files, Claude opens only the ones needed for the concrete step it is running.

The result is that you can have dozens of skills installed while occupying a minimal fraction of context, and each one can be as detailed as needed. A skill for quarterly planning can carry your whole planning template, a checklist of the inputs you always request, and two finished examples from past quarters, and all of that material stays out of the way until the exact moment it becomes useful. A financial analysis skill can include a Python script for calculations and a reference document with accounting definitions, and Claude will only read that material when the task asks for it.

## Where you can use skills

Skills work across three main surfaces. On Claude.ai you enable them from settings: Anthropic ships official skills for creating and editing Word documents, spreadsheets, presentations, and PDF files, and you can upload your own when your plan allows it. In Claude Code, skills live as folders inside the .claude/skills directory of your project or personal configuration, and the agent discovers them automatically while working in that project. For developers, the Agent SDK and the API allow loading skills into your own applications, so an agent built on Claude inherits the same procedures.

This cross-surface coverage is one of the format's practical advantages: the same skill you use on the web can accompany you in the terminal and in an internal application, with identical behavior.

## Which procedures are worth turning into a skill

The best candidates share three traits: they repeat often, they have a recognizable correct shape, and today they depend on instructions someone dictates from memory. Some concrete examples that work well:

- Recurring reports with a fixed format: weekly project updates, month-end closes, metrics summaries.
- Reviews with your own criteria: code with team conventions, copy with the brand style guide, proposals with the approved sales structure.
- Operational documents: meeting minutes, work plans, internal announcements with mandatory sections.
- Analysis with mechanical steps: data cleanup, recurring calculations, comparisons with a defined methodology.
- Context onboarding: everything you would explain today to a new teammate about how something gets done in your team.

The practical rule is simple: if you have written the same email or the same prompt three times in a month, that procedure is asking for a skill.

![Doodle of three stacked boxes with a magnifying glass and an orange key](https://jonathancanales.com/content/images/2026/10/p4-doodle2-2.png)

## How to create your first skill step by step

The whole process fits in an afternoon, and most of the time goes into thinking through the procedure, which is the part that adds the most value. Writing the skill is transcribing that clarity into a format Claude can follow.

Start by picking a procedure you repeat frequently with a recognizable correct shape: a weekly report, a code review, meeting minutes. Repetition is the signal that encapsulating it pays off.

Create a folder with the skill name and a SKILL.md file inside. The YAML header carries the name and the description, and the description deserves special attention: it is the only thing Claude always sees, so it must explain what the skill does and in which situations to activate it. Then write the instructions in markdown, with numbered steps, quality criteria, and concrete input and output examples.

A minimal SKILL.md looks like this:

```bash
---
name: executive-minutes
description: Turns raw meeting notes into executive minutes with agreements, owners, and dates. Use it when the user shares meeting notes and asks to organize or summarize them.
---

# Executive minutes

## Steps
1. Read the full notes and identify the topics covered.
2. Extract every agreement with its owner and commitment date.
3. Write the minutes with fixed sections: summary, agreements, open items, and next meeting.
4. Close with a list of needed confirmations whenever a detail stays ambiguous.
```

If the procedure includes calculations or mechanical transformations, add a script to the folder and reference its use from the instructions. Claude runs the script in its environment when appropriate, which gives consistent and auditable results. If the procedure depends on lengthy reference material, store it as a separate file and mention it at the exact point where it is needed.

Install the skill on the surface you use: the .claude/skills folder in Claude Code, or the file upload in Claude.ai settings. Then test it with real cases. Ask for the task in different ways, with clean inputs and messy inputs, and watch where the output drifts.

## Good practices that make the difference

The description decides when the skill activates, so write it thinking of the phrases a user would say when needing it, concrete verbs included. A vague description leaves the skill asleep; a precise description activates it at the right moment.

Keep instructions imperative and numbered. Claude follows explicit procedures better than aspirational paragraphs. Include verifiable quality criteria: maximum length, mandatory sections, date format, expected tone. Whatever you can verify, Claude can verify as well before delivering.

Iterate with evidence. When an output drifts, adjust the exact instruction that caused it rather than rewriting everything. Good skills grow through small, accumulated corrections, just like a team's living documentation. Keep skills in git: the change history tells you which adjustment improved which behavior.

Sharing multiplies the value of every skill you write. A skill in a team repository becomes common property: anyone can use it, anyone can improve it, and improvements benefit everyone who runs it afterward. Teams that document procedures this way also discover a valuable side effect: writing the skill forces clarity on the procedure itself, and more than once that exercise reveals ambiguous steps nobody had noticed.

Version control also lets you roll back an adjustment that made things worse, which happens more often than anyone expects during the first weeks of a new skill.

Finally, one skill per procedure. A skill mixing five different tasks confuses activation and dilutes the instructions. Five focused skills compose better: Claude can use several in the same conversation when the work asks for it.

## How to know your skill works

The test of a skill is consistency, and measuring it takes minutes. Run the same task five times with different inputs and compare the results: the structure should stay stable and the differences should come from the content alone. If every run comes out with a different shape, the instructions are still ambiguous somewhere.

Testing the edges is also worthwhile. Ask for the task with incomplete information and check that the skill asks for clarification instead of inventing data. That behavior comes from declaring it explicitly in the instructions, with a needed-confirmations section like the one in the example.

When the skill survives those tests, it is ready for daily work, and it is worth noting the date of the last review inside the file itself to keep the improvement habit going. From there, every use feeds the next refinement, and the procedure that used to live in your head becomes a team asset. If you also use Claude Code daily, the guide on [how to install Claude Code and finish your first project](https://jonathancanales.com/en/how-to-install-claude-code-first-project/) helps you get the environment ready, and the comparison of [Codex vs Claude Code: workflow differences](https://jonathancanales.com/en/codex-vs-claude-code-workflow-differences/) shows where skills fit inside your complete workflow.

## Sources

- [Agent Skills introduction](https://www.anthropic.com/research/equipping-agents-for-the-real-world-with-agent-skills?ref=jonathancanales.com)
- [Agent Skills documentation](https://docs.claude.com/en/docs/agents-and-tools/agent-skills?ref=jonathancanales.com)
- [Skills support on Claude.ai](https://support.claude.com/en/articles/12512180-what-are-skills?ref=jonathancanales.com)