Create your first Claude skill and fix it until it holds up

Claude, Anthropic's AI assistant, can load your working methods on demand. Anthropic calls these methods Agent Skills, which you'll also see called Claude Skills. Most people simply say “skills.”

Searching in French, I find 8 pages that already explain how to write a SKILL.md file. They all stop at the moment the skill works for the first time. That moment is the easiest part of the process.

I've been running content skills since late June 2026, 11 of them today. As of October 28, my production log has 448 entries that went through them, including 38 LinkedIn posts. The skill that writes those posts needed 4 fixes to stop making things up, and those fixes are what made it reliable.

What exactly is a Claude skill?

A folder. Inside, a SKILL.md file written in markdown, with a metadata block at the top. Nothing else is required.

The file can come with other documents and scripts, which Claude opens only if it needs them. Anthropic introduced the format in October 2025 and has since opened it up as a public standard, AgentSkills.io, which means the same folder works in the Claude app, in Claude Code, through the API and in other tools that follow the standard.

Claude loads a skill in 3 stages.

1. At the start of a session, Claude receives only the name and description of each of your skills. A few lines each.
2. When your request matches a description, it reads the body of the SKILL.md in full.
3. If the file points to supporting documents, it opens them only when it needs them.

Anthropic calls this progressive disclosure. The practical consequence: 40 pages of documentation sitting next to the SKILL.md cost nothing as long as nobody asks for them. The description, on the other hand, is paid for in every session.

It also answers the question that comes up most often in workshops: how a skill differs from a Claude project. A project is a place, with its documents and instructions loaded permanently. A skill is a portable capability, loaded on demand, that follows the same format everywhere. It's one of the 5 components of an AI agent, the one that carries what it knows how to do.

Your first SKILL.md in 20 minutes

Start from a task you redo every week. For me, it was proofreading: I kept pasting the same writing rules into the conversation, again and again.

Here's the minimal file. It fits on one screen, and it works.

---
name: review-before-sending
description: Reviews a marketing text before publication and flags AI writing tics and unsourced numbers. Use when the user asks to review, check, proofread or approve a post, an email, a newsletter or a page before sending it.
---

Review the text provided and return 3 blocks, in this order.

1. Verdict: ready to publish, ready after fixes, or needs rework.
2. The faulty passages, quoted word for word, with a suggested rewrite.
3. What works well, in one line.

Flag first: sentences that negate an idea before stating the right one,
em dashes, paragraphs longer than 3 sentences,
and any number that isn't tied to a verifiable source.

Never rewrite a passage that already complies.

The skill's name, identical to the folder's, becomes the command. This file gives you /review-before-sending, and Claude also loads it on its own when you ask it to review something.

The metadata block has 2 constraints, and Anthropic's best practices documentation spells them out in black and white.

The name is 64 characters at most, in lowercase letters, numbers and hyphens, and it can't contain “claude” or “anthropic.” The description is capped at 1,024 characters. For the body of the file, the same documentation advises staying under 500 lines and, beyond that, splitting the content into supporting files.

To test it, open a fresh session and phrase the request the way you naturally would. If Claude loads the skill without your calling it by name, the description is good. If it doesn't, the description is missing your own words.

Without a terminal, the same file goes through the Claude app. Zip the skill folder, keeping the folder itself at the root of the ZIP, then import it from the Skills section of the Customize menu: the + button, then “Create skill” > “Upload a skill.” Anthropic's official help states that code execution must be enabled, and that skills are available on every plan, free included.

The skill I use every day

Mine is called my-viral-post. It writes my LinkedIn posts in my voice, based on an analysis of my last 100 posts and on my editorial doctrine. It's part of a complete agent, published as a free template: create your LinkedIn agent with Claude Code.

Its real description, translated from French and trimmed to fit the block:

---
name: my-viral-post
description: Writes a new LinkedIn post in Jessy Martin's proven style,
  based on what has already worked for him (analysis of his last 100
  posts + his editorial identity + his voice DNA).
  Trigger this skill whenever Jessy wants to write a post that sounds
  like him: "write me a LinkedIn post", "give me angles for a post",
  "help me post this week". The skill first asks for the right
  material, offers several angles to choose from, then assembles the
  complete post in his voice, with clear direction on the visual.
---

Look at what this description does. It says what the skill produces and which phrases should trigger it. The phrases in quotation marks are the ones I actually type.

The file is 176 lines long. It holds my voice and my cadence, my registers ranked by actual performance, my 3 highest-reach posts with an analysis of what worked, the vocabulary blacklist, and the visual template to pair with each topic.

The first version contained none of that. It was my prompt at the time, copied into a file. It produced posts that read fine and were wrong.

The 4 fixes that made it reliable

Each one comes from a failure observed on real production. None of them could have been anticipated when I wrote the file.

1. Ask for material before writing

The first flaw was the most serious: without material from me, the skill made things up.

An engagement with a client I never had. A breakthrough moment that never happened, backed by a plausible and false number.

It makes sense. Ask it for a post in the voice of someone whose signature is lived experience backed by numbers, and it manufactures lived experience backed by numbers.

The fix fits in one instruction, placed at the top of the method: ask the questions first, generate second. Get the raw material, then write. Since then, the skill stops and asks which engagement the post is about before producing a single line.

2. Let the last 5 approved posts override the historical analysis

The skill was calibrated on my 100 posts from before June 2026. My style has shifted since, and above all I've settled specific points along the way.

A frozen skill replays the version of you from the day you wrote it. It pulls you back to your past, politely, every time you invoke it.

The fix: an instruction at the top of the file that sends Claude to read my last 5 approved posts in my production log before writing anything, and states that those 5 posts win over the historical analysis whenever they diverge. The skill recalibrates itself with every publication.

3. Be wary of your own signature

My most recognizable hook is an unsettling statement followed by a colon. The skill picked up on it, and put it everywhere.

3 posts in a row with the same opening mechanism, and the signature becomes a formula. The fix is an explicit rule: don't reuse the colon hook on 2 consecutive posts, and flag when a draft leans too hard on a move used recently.

That guardrail took me 3 weeks to figure out. A skill that applies your recipe perfectly wears it out faster than you do.

4. Check every number against its original source

On August 31, I was preparing a post on Stanford's annual AI report. I asked for a line-by-line check against the PDF, page by page, before publishing.

4 errors, on numbers I would have published:

• a survey attributed to the wrong institute and the wrong year;
• the same attribution error copied onto 2 slides of the carousel;
• a “nearly 20%” that had become “20%”;
• 2 numbers from the report placed side by side in a sentence that implied they described the same model, which the report says nowhere.

These 4 errors were plausible, and that's what makes them dangerous: they get past a human proofread.

The rule I've applied since, to copy into your skill:

## Third-party numbers

Any number taken from an external source is checked against the
original document before publication: the PDF or the official page
of the organization that first published it.

For each number, record in the production notes:
- the exact value as written in the source, with the page
  or figure it comes from;
- the organization that produced the data, and the year of fieldwork
  (it often differs from the report's publication year).

If a number can't be tied to its page, it comes out of the text.

What these 4 fixes have in common: each one comes from an observation. I watched the skill get it wrong on a real deliverable, then I wrote the rule.

The same Anthropic documentation recommends building your test cases before writing the skill, and comparing the result with and without it. Same principle: measure a gap, then correct it.

I always advise adding a 2nd skill that checks the first. Mine is called brand-check-jessy. It runs 6 checks in a fixed order and returns a verdict with the faulty passages quoted word for word. It's one of the 10 AI agents that work on my marketing every week.

No content goes out without its green light. A skill that produces and a skill that checks go wrong in different ways.

When a rule has to hold every single time, I hand it to a hook, which fires on its own and can block the action in progress. The method is in controlling your AI agents with Claude Code hooks.

How does Claude know which skill to use?

Through the description, and the description alone. It's the field people rush through, and the one that decides everything.

2 rules are enough. Write in the 3rd person, because the text is injected into the system instructions and an “I can help you” creates confusion there.

Then say what the skill does and in which situations to use it, with the real trigger phrases: the ones you type, and their synonyms.

Compare.

# Never triggers
description: Helps write marketing content.

# Triggers
description: Writes a client newsletter from the week's notes, in the
  editorial guidelines of the brand concerned. Use when the user asks
  "write the newsletter", "prepare this month's email", "what should we
  send this week", or provides raw notes and asks to turn them into
  an email.

The description also has a cost, and that cost settles the question of how many skills to keep. Claude Code loads the list of names and descriptions into the context of every session, and its documentation states that this budget equals 1% of the model's context window. Each entry is also capped at 1,536 characters, description and when_to_use field included.

When the list overflows, Claude Code drops entire descriptions, starting with those of the skills you invoke least. The name stays in the list, without the keywords that used to trigger the skill. Claude then no longer knows when to call your rarest skills, at the precise moment you'd need them.

The /doctor command gives an estimate of what this list costs and of its biggest contributors. It's the first thing to check when a skill stops triggering for no apparent reason. The /skill-doctor command details what each skill costs and how often it's used, so you can decide which ones to disable.

When a skill is a waste of effort

This is the question that saves the most time.

Writing a skill is wasted energy in 2 situations.

Information. Your color palette or your product names live in the CLAUDE.md file at the root of the project, loaded in every session. A skill is there to carry a procedure or a checklist.

The boundary is simple: if it's information, it goes in CLAUDE.md, and if it's a sequence of steps, it's a skill. I detailed this split in my article on building a website with Claude Code, where the CLAUDE.md drives the whole design system.

Dated information causes one more problem. A product line's prices or a rule that changes on January 1 quietly make a skill wrong, and a skill is much harder to audit than a documentation page. Anthropic recommends avoiding any dated information in a SKILL.md, or putting it in a clearly labeled “old patterns” section.

What the model already knows. The most common case, and the most costly. Explaining to Claude what a persona is or what an open rate means: every line of that kind is a context cost for zero gain. Anthropic's documentation poses the question to ask about every paragraph, and it's blunt: does Claude really need this explanation?

Hence my position on how many skills to keep. 3 well-written skills beat 40 installed ones. The list budget is a mechanical reason. Name collisions are another: 2 public repositories can ship a “content-strategy” skill with different behaviors, and the documented resolution order often surprises people, with a personal skill winning over a project skill of the same name.

Above all, a skill you didn't write encodes someone else's trade-offs. It produces a clean, generic result, far from your brand and your method. What makes a skill useful is precisely what's written nowhere else.

If you're looking instead for an overview of what already exists and what the big public repositories are worth, I compared the best Claude plugins and skills for marketing in a dedicated article, with adoption numbers for each one.

Where skills live and how to share them

A skill can live in 5 places, and each one grants different rights.

The trap lies in how skills are picked up from parent folders. Claude Code reads the skills in the folder where you open the session and in all its parent folders up to the root of the repository. Skills placed in a subfolder show up only when Claude touches a file in that subfolder.

In practice: I open a session at the root of my brand repository, my 5 cross-cutting skills respond, and my 11 content skills stay silent. They live 3 levels down. That's the documented behavior, and it had me searching for a good hour the first time.

2 habits settle the question. An inventory file at the root that says where to open the session to get what. And symbolic links: my SKILL.md files live in a human-readable skills/ folder, and .claude/skills/ contains only links to them. Claude Code follows the links without a hitch.

# Skills stay filed with the doctrine they apply
mkdir -p .claude/skills
ln -s ../../skills/my-viral-post .claude/skills/my-viral-post

# Check what Claude Code will actually load
find . -name "SKILL.md" -not -path "*/dist/*" | sort

The Claude app and Claude Code cloud sessions load only the skills enabled on your claude.ai account. A personal skill that works in your terminal can't be found there until you've imported it on the account side.

In the other direction, syncing is automatic. Since version 2.1.273, Claude Code connected to your claude.ai account downloads your enabled skills to ~/.claude/skills/synced/, read-only: a change made there can be overwritten at the next sync. To change a synced skill, edit it on claude.ai.

One hygiene rule applies to everyone: a project skill is plain text, committed to Git and readable by everyone who has the repository. Your API keys and your clients' data have no place there.

Once you have 3 or 4 skills in production, 2 mechanisms take over.

Subagents. By adding context: fork to the metadata, the skill runs in an isolated subagent: it doesn't see your conversation, and its result comes back when it's done. That's what I use for long tasks like market monitoring, which would otherwise fill the whole session with intermediate content.

Plugins. A plugin is a folder that bundles skills, subagents, hooks and MCP connections. Its .claude-plugin/plugin.json manifest is optional: it describes the plugin and its settings. It's the format to choose as soon as you share with a team, because the skills inside it are prefixed with the plugin's name and can no longer collide with your colleagues'. Plugins can also be added in the Claude app, on paid plans.

They're distributed through a marketplace, a public or private Git repository that lists them. Anthropic publishes 3 general-purpose ones, including the official one, which Claude Code adds on its own, plus themed catalogs such as anthropics/skills. A company can host its own in a private repository to distribute its internal procedures.

The skill-creator plugin, on the official marketplace, runs your test cases in isolated subagents and compares the result with and without the skill, or between 2 versions of the same file. That way you check that a change actually improves the skill before you keep it.

/plugin install skill-creator@claude-plugins-official
/doctor

Conclusion

Writing a first Claude skill takes 20 minutes. Making it reliable takes weeks, and you pay for it in observation.

My method comes down to 4 moves.

1. Start from a task you really do over and over.
2. Write a description with your own trigger words.
3. Watch the skill work on a real deliverable, and note every gap.
4. Rewrite the file based on what you saw.

The rest follows on its own. And if you want the foundation before you start, my guide to learning Claude covers the basics in 2 hours, and the Claude Code path goes further on the terminal side. To find out where AI would save your marketing the most time, the free assessment gives you your score and your priority actions in 6 minutes (the report is in French).

What's the task you re-explain to Claude every week?