How to create a Claude skill for your team in 2027

Key takeaways:

• Build first for the task your team repeats and re-explains most. On a content team that's usually a brief builder, a first-draft pass or an editing pass.
• A skill is one folder with a SKILL.md file whose header holds a lowercase, hyphenated name (64 characters at most) and a description of what the skill does and when to use it.
• Keep the description under 200 characters if you upload to claude.ai, because Anthropic's help center sets that limit even though the open Agent Skills spec allows 1,024.
• Test in a fresh chat with the skill off and then on, and hand it to a teammate cold before anyone relies on it.

Most skill tutorials stop at the anatomy diagram, and the skills they produce are demos: impressive once, unused by the second week. A team skill is a different thing. It does the job your team repeats every week, to your standards, without anyone typing the standards out again.

This Claude skill tutorial is the step-by-step answer to how to create a Claude skill your team will actually use, written for people who don't code. It covers choosing the first job, the four ways to build one, a complete worked example for a content team, the instruction and description craft, testing, and sharing. The mechanics come from Anthropic's own documentation, checked against each surface where skills run.

I run busyless as a fractional Head of Content, and the rule I build skills by is the one I teach in my free course: the second time you explain the same procedure in chat, stop and write the skill instead. You're already paying the cost of the instructions. You're just paying it every week and keeping nothing.

What to build first

The right first skill is the task your team repeats most and re-explains most, in that order. Repetition decides whether the skill gets used, and re-explaining tells you the standards exist somewhere, even if only in one person's head.

On a content team, three jobs usually win. A brief builder takes a keyword and sources and returns a brief in your format. A first-draft writer takes a brief and returns a draft in your voice. An editing pass takes any draft and applies your banned-words list and structure rules. Those are the brief, draft and edit stages of a content pipeline, and each one recurs weekly.

The test for whether a procedure belongs in a skill fits in four questions, all taken from the same course lesson. Is it a procedure with steps rather than a single rule? Does it apply to only some of your work? Is it long enough that pasting it into chat is annoying? Have you explained it more than twice? Four yeses means build it.

What not to build first is the impressive one. Multi-step research agents and creative generators demo well and fade quietly, because their standards are hard to write down and their failures are hard to trace.

An r/ClaudeAI walkthrough for non-technical users on setting up skills lands on the same advice from one user's experience: start with something simple you already do regularly, and figure out the rest as you go. Its menu paths predate the move to Customize > Skills, a change a commenter points out.

Four ways to build a Claude skill

Anthropic now offers several routes to the same SKILL.md file, and the right one depends on your plan and how much control you want. The table compares the four, with the availability Anthropic states for each.

The conversational route is the one to try first if you don't code. In Claude's thinking you'll see it read a skill-creator skill, which carries Anthropic's own authoring practices, before it builds your folder. Start a chat with something like "I want to create a skill for our content briefs", upload a template and an approved example, and answer its questions in enough detail that a capable stranger could follow your process.

To build a Claude skill by hand instead, or to create Claude skill files you can version alongside your style guide, you need to know what goes in the folder. Even if Claude writes the first version, you'll be the one editing it, so the anatomy is worth learning either way.

The anatomy of a skill folder

Every skill is a directory with a SKILL.md file at its root. The file opens with YAML frontmatter, a header between two lines of three dashes, which holds the name and description. The rest is Markdown instructions. Anything else in the folder is optional: the open spec at agentskills.io suggests references/ for documentation, assets/ for templates and scripts/ for code.

The frontmatter rules are strict, and two of the help center's listed upload failures come straight from breaking them. Between them, Anthropic's developer overview, the open spec and the help center's guide to creating custom skills set these limits on the two required fields:

• The name holds at most 64 characters, using only lowercase letters, numbers and hyphens.
• The name can't contain the reserved words "anthropic" or "claude", so claude-brief-helper fails.
• The folder name must match the name, so a skill called brief-builder lives in a folder called brief-builder.
• The description can't be empty and can't contain XML tags.
• The description tops out at 1,024 characters in the spec, but the help center caps it at 200 for claude.ai.

The safe move is to write for the stricter limit, so the same file works everywhere. Claude Code accepts extra fields, such as argument-hint and disable-model-invocation, that a claude.ai upload rejects with an "Unexpected key(s)" error. For a skill your whole team will use in Claude's apps, stick to name and description.

Two size rules keep the body readable for Claude. Anthropic's authoring guide recommends keeping the SKILL.md body under 500 lines and moving detail into reference files that link straight from SKILL.md, one level deep. A reference file longer than 100 lines should open with a table of contents, so Claude sees its full scope even when it previews only part of it.

Claude skill examples: a brief builder, written out

Abstract anatomy only goes so far, and Claude skill examples are most useful when they're built around real work, so here's a complete skill a content team could upload today. It's modeled on the seven-part brief from the content brief automation I build for clients, which turns one keyword into a writer-ready brief in about five minutes. The folder looks like this:

brief-builder/
├── SKILL.md
└── references/
    ├── brief-template.md
    ├── brief-rules.md
    └── approved-brief.md

The SKILL.md itself is short, because the detail lives in the three reference files. This is the whole file:

---
name: brief-builder
description: Builds a seven-part content brief in our house format from a target keyword and source links. Use when someone asks for a content brief or an article outline.
---

Brief builder

Turn one target keyword and two to five sources into a brief a writer can draft from without asking a single question.

Before you start, ask for anything missing: the keyword, who the reader is, and the sources or notes.

Steps
1. Read every source and list the claims each one supports.
2. Decide the article type: comparison, alternatives, how-to or deep-dive.
3. Write the working title, the funnel stage and the goal of the piece.
4. Outline 6-10 sections in the order a reader needs them, and under each one note the source and the fact it carries.
5. Pick up to 10 supporting keywords that a reader would actually type.
6. If web search is available, name the strongest article already ranking for the keyword and note what it does well.
7. Check the brief against references/brief-rules.md before returning it.

Output
Use the layout in references/brief-template.md exactly. Match the tone and depth of references/approved-brief.md.

Never invent a statistic, price or quote. Write "source needed" instead.

Each choice in that file is deliberate. The description names the output and the two requests that should trigger it, in the third person, and stays under 200 characters.

The steps are numbered because their order matters, while the rules that apply to every brief sit in brief-rules.md, where an editor can change them without touching the procedure. And approved-brief.md is a real brief your team signed off on, which teaches Claude your quality bar faster than any adjective.

The other two reference files are where your team's knowledge goes. brief-template.md is your brief layout with the headings filled in and the content blank. brief-rules.md holds the standards a strategist would otherwise repeat in every review: how many sources a section needs, which claims need a link, and what a working title may not do.

Writing instructions a team can edit

The instruction craft is where most people learning how to create a Claude skill go wrong, and the rule is simple: write rules a colleague could follow, not prompts you'd paste. "Open with the customer's own words from the transcript. Keep every section under four sentences. Every claim needs a source from the references folder." Anyone on the team can read, check and change those, which matters because the skill will outlive whoever wrote it.

Anthropic's authoring guide starts from a default assumption that cuts most first drafts in half: Claude is already very smart. It doesn't need to be told what a blog post is or why sources matter, so every sentence should carry something Claude couldn't guess, such as your format, your thresholds or your exceptions. A skill that explains the obvious wastes the context the important rules need.

Match how tight a rule is to how fragile the step is. Where there's one right way, such as the brief's section layout, be exact. Where judgment helps, such as choosing which source opens the piece, describe what good looks like and let Claude decide. A coverage rule shows the difference well: "cover every subtopic a reader expects before going deeper", the structural idea behind topical relevance, leaves room for judgment while still being checkable.

Named examples beat adjectives every time. "Keep it tight" is a wish; "under four sentences, opening with the customer's quote" is a rule, and the approved example in the folder shows what following it looks like. Anthropic's help center lists examples among the marks of a good skill, alongside a focus on one workflow rather than everything.

Write the description that decides when it fires

The description is the one line Claude reads before deciding whether to load your skill at all, so it deserves more care than any paragraph in the body. Anthropic's authoring guide sets three rules for it. Write it in the third person, because it's injected into Claude's system prompt and "I can help you" confuses discovery. Cover both the job and the situations that should trigger it. And include the words people will actually type.

That last rule is the same principle behind B2B keyword research: use the vocabulary your team really uses, not the one you'd prefer. If your editors say "outline" and the description only says "brief", a lot of requests will miss. The table shows three weak descriptions and how to fix each one.

Every stronger version stays under 200 characters and ends on its trigger. If a skill still fires where it shouldn't, Anthropic's Claude Code docs give two fixes: make the description more specific, or, in Claude Code only, add disable-model-invocation: true so it runs only when someone types its name.

Package it and upload it

On claude.ai a skill travels as a ZIP file, and the ZIP's shape matters. The help center's packaging rules are short. The folder name has to match the skill's name, and the ZIP must contain that folder at its root, so brief-builder.zip opens to a brief-builder folder, not to a loose SKILL.md.

To upload it, go to Customize > Skills and use the "+" button, where "+ Create skill" leads to the "Upload a skill" option for your ZIP. If the upload fails, the help center names four usual causes: a ZIP over the size limit, a folder name that doesn't match the skill name, a missing SKILL.md, or invalid characters in the name or description. Fix the one that applies and upload again.

You don't have to re-upload for every small change while you're still iterating. When you work on a skill with Claude in chat, the files open beside the conversation, and you can highlight text, click "Edit with Claude" and type the change. For a multi-file skill, leave requests across several files and send them together. If you upload a new version by hand, switch the old one off so the two don't compete. Once it is uploaded, our guide to using Claude skills covers turning it on and checking that it fires.

In Claude Code there's no packaging at all. Save the folder as ~/.claude/skills/brief-builder/SKILL.md for yourself, or as .claude/skills/brief-builder/SKILL.md inside a repository so everyone who clones it gets the skill. Type /brief-builder to run it, or ask for a brief and let the description match.

How to create a Claude skill that passes the test

A skill isn't done when it runs. It's done when it beats the version of the job without it, and Anthropic's Claude Code docs put the reason plainly: seeing a skill trigger tells you Claude found it, not that it did what you intended.

The help center's checklist covers the first half. Before upload, check the description, confirm every referenced file exists and try example prompts; after upload, try several prompts that should trigger it and look for "Reading [skill name]" in Claude's thinking.

The second half, and the step that separates a demo from a team tool when you learn how to create a Claude skill, is comparing outputs. Anthropic's authoring best practices recommend building three test scenarios first and measuring Claude without the skill as a baseline. Run each scenario in a fresh chat, because leftover context from writing the skill hides gaps in it. These four checks make a practical gate before a skill reaches anyone else:

The stranger check is the one that predicts adoption. If output quality depends on who runs the skill, it's leaning on private knowledge that belongs in the reference files, which is the case for content engineering in miniature: standards that live in files instead of heads.

If your team works in Claude Code, Anthropic's skill-creator plugin automates this loop. It runs each test case with and without the skill, grades the results and tunes the description against prompts that should and shouldn't trigger it.

Rolling out Claude skills for teams

A skill only one person can run isn't a team asset yet. Sharing Claude skills for teams takes a minute on a Team or Enterprise plan. Open Customize > Skills, find the skill, click the three-dot menu and choose "Share", then pick specific people or, on Enterprise, a group. Recipients see it grayed out until they switch it on.

Shared skills are view-only, and when you update yours, everyone you shared it with gets the new version at their next use.

Publishing goes a step further and hands the skill to your organization's library. Click "Publish to org", and if your organization requires review, propose whether the skill should be available to install, installed by default or required. A reviewer approves it and chooses who gets it, and later updates go through the same review. Owners control all of this, and the group and organization sharing toggles start switched off.

In Claude Code, the equivalent is committing .claude/skills/ to the repository, or packaging skills into a plugin for wider distribution. Whichever route you use, keep a one-line changelog at the bottom of SKILL.md with a date and what changed, so the next editor knows why a rule exists.

Skills decay the way pages do, as standards move and the examples age. Review each one quarterly and make the same refresh, rewrite or retire call that advanced content optimization makes about a slipping page. A skill nobody has triggered in a quarter is a retire.

How I keep a skill set maintainable

The busyless writing system shows what happens once there are more than a handful of skills. Three of its skills write different kinds of roundups, and they share about 70% of their instructions: how to research, build the comparison table and write each entry. That shared part lives in one reference file that all three read, and each skill adds only what makes its own type different.

The payoff is that changing how comparison tables work means editing one file, not three. Three copies of a rule are three chances for them to disagree, and the copies drift apart the first time someone fixes only one of them.

The second habit is writing every fix down where the next session will read it. When I built busyless.space with Claude Code, the tool wrote a fix for every library quirk we hit and logged it in a "things to watch for" file, which every later session read before starting. A skill's reference files deserve the same treatment: when a reviewer catches a mistake, the rule that prevents it goes into brief-rules.md that day.

Build it with me in the free course

The same approach, built step by step, is the skills lesson in module two of the free course, which runs to 27 lessons with no signup and leaves you with six files you keep. It uses Claude Code rather than the claude.ai interface, so it suits a team ready to run skills from a repository, which is where this Claude skill tutorial leaves off.

If you'd rather your team learn this on its own workflows, that's the shape of busyless AI enablement: over six months we rebuild one of your workflows each month, and by the end your team runs them without me. And if the honest answer is that this guide and one afternoon will do, I'll say so. Book a 30-minute call.