The first time I watched an analyst try to write a Claude skill, she made it about twenty seconds before she said, "Wait, what is the dashes thing." She meant the YAML frontmatter. She had a perfectly good answer to "when should Claude run this," three pages of it from a Notion doc, but the tooling wanted that answer expressed as a key called description between two --- lines, indented correctly, under 1024 characters. She closed the laptop.
That is the problem this article is about. A Claude skill is a small thing and the format is open. The format is also written for people who already know what a YAML frontmatter block is, and the people with the actual expertise to put inside the skill, the lawyers and underwriters and product marketers and field engineers, mostly do not. The skill format has a structural bias toward whoever can write Markdown with metadata, not whoever knows the work.
This is a walk-through for the second group. By the end you should know whether you can hand-roll one this afternoon or whether you want help.
What a skill actually is
A Claude skill is a folder. Inside that folder is a file called SKILL.md with two parts: a metadata header in YAML, and instructions in Markdown. That is the whole format. Optional companion files can sit next to it: scripts Claude runs, reference docs Claude reads only when needed, examples, templates. The folder lives on disk somewhere Claude can find it, either ~/.claude/skills/<name>/ for your personal library or .claude/skills/<name>/ checked into a repo for a team.
When you ask Claude a question that matches the skill's description, the skill loads automatically. You can also call it directly by typing /<skill-name>. The contents of SKILL.md enter the conversation as instructions, and Claude follows them. Anthropic's docs describe the same idea: "Create a SKILL.md file with instructions, and Claude adds it to its toolkit."
The toolkit metaphor holds. A skill is what a senior person on your team would write down for the new hire, except the new hire is Claude and reads it every time the relevant question comes up. A redlining skill for a contracts lawyer. A pricing-guidance skill for a sales engineer. A QBR-narrative skill for a CSM. A "convert this messy CSV into our finance-team format" skill for whoever inherits that work. The format is the same in every case. The expertise is what changes.
The open standard means a skill you write today runs in Claude Code, in claude.ai through Settings > Features, and through the Claude API with the right beta headers. It also runs in third-party tooling that adopted the same spec, and turns up on marketplaces like SkillsMP, which indexes over a million public skills. Where to publish and what to check before installing is its own piece.
The hand-authoring path
Without help, here is the sequence.
Create a directory under ~/.claude/skills/ with a short lowercase hyphenated name like redline-msa. Inside it, create SKILL.md. Type three hyphens, your YAML metadata, three more hyphens, then your instructions in Markdown. Save. Restart Claude Code if you created a brand new top-level skills directory; otherwise it picks up live.
A minimal real-world example, the kind a lawyer might write for a vendor master service agreement review, looks like this:
---
name: redline-msa
description: Reviews a vendor MSA for risk and proposes redlines. Use when the user asks to redline an MSA, pastes an MSA, or asks "is this contract okay." Flags indemnification, IP assignment, auto-renewal, limitation of liability, and data privacy clauses against our standard playbook.
allowed-tools: Read Grep
disable-model-invocation: false
---
## What to do
When the user provides a contract, identify the contract type first. If it is not an MSA, say so and stop.
For an MSA, walk through the document section by section and flag any of the following...
That is the basic shape. Five lines of metadata, then the actual playbook. The Anthropic skills repo on GitHub has more involved examples worth reading; the PDF skill is a good reference because it shows the multi-file pattern with SKILL.md, a FORMS.md companion for the form-filling subroutine, a REFERENCE.md for the deeper API surface, and a scripts/ folder.
So far, so simple. Now the gotchas.
The name field has rules: lowercase letters, numbers, and hyphens, max 64 characters, and the words "anthropic" or "claude" are off-limits. The description is capped at 1024 characters and is the single most important field, because Claude reads only the description across all your installed skills when deciding what to load. Vague description, skill never fires. Too long, it gets truncated at 1,536 characters when combined with the optional when_to_use field. Put the trigger phrases first. Put the key use case in the first sentence. Treat it like an ad headline competing against every other skill on the machine.
Then there are roughly a dozen optional fields. allowed-tools decides which tools Claude can call without asking permission, with optional argument restrictions like Bash(git add *). disable-model-invocation controls whether the skill auto-loads or only fires when called by name. user-invocable decides whether it shows in the slash menu. context: fork runs the skill in an isolated subagent. paths restricts it to certain file globs. model and effort override the active model for the turn. argument-hint and arguments declare positional parameters. All of them fail silently if you get the syntax wrong, so the skill just quietly does the wrong thing.
The Markdown body has its own conventions. The docs recommend keeping SKILL.md under 500 lines, because once loaded, the body stays in the conversation for the rest of the session and every line is a recurring token cost. So you move long reference material to companion files and link to them from SKILL.md, which means deciding which content goes inline and which goes in a separate file Claude reads on demand. There is shell-injection syntax (!`command`) that runs a command at load time and inlines its output. Handy for grabbing the current git diff or a live PR description. Easy to misuse. There are string substitution variables ($ARGUMENTS, $0, ${CLAUDE_SKILL_DIR}) that look like Bash but follow their own rules.
None of this is hard for an engineer. All of it is a wall for everyone else.
The honest answer to "how long does hand-authoring take" is: a few hours for a competent developer who has done it before, a full day for one who has not, and somewhere between "never finishes" and "produces something that almost works" for a non-developer working from the docs. The blocker is rarely the domain knowledge. It is the format.
The no-code path
If you want to ship a skill without learning YAML, you describe what the skill should do to a Claude skill builder that knows the format, and the tool writes the folder for you. People also call this a Claude code skill creator since most of these skills target Claude Code.
Knack is one option here. The interview runs six phases covering what the skill is for, who triggers it and when, what inputs it expects, the actual procedure, what good and bad outputs look like, and what tools it should be allowed to call. Each phase is a conversation, not a form. The output is a real SKILL.md folder with valid frontmatter, an instructions body in Markdown, and any supporting files the procedure needs. Drop it in ~/.claude/skills/, commit it to a repo, ship it to teammates, upload it to claude.ai, or publish it anywhere that reads the Anthropic Skills standard. The file is the same file an engineer would have hand-typed; there is no proprietary container.
There is a structural argument underneath the ergonomics one. The bias in skill authoring today shows up in who ships. Engineers who can write skills usually lack the domain expertise to make them good. Domain experts who could make them good cannot get past the syntax. So the skills that exist tend to be thin (productivity helpers, review helpers, deploy scripts), or watered-down expert workflows where an engineer translated for an expert and dropped half the nuance. The expert writes a fourteen-step pricing methodology. The engineer turns it into "check the discount tier and apply it." Both people leave the meeting frustrated.
Anyone with deep domain knowledge should author their own skills directly, not dictate them to a translator. That is the take.
The obvious objection is lock-in. If a tool writes my skill, am I tied to that tool. The answer depends on what the tool emits. Any builder that produces plain files following the open spec leaves you free to edit them in any text editor afterwards. Hand-tune the allowed-tools field, split the instructions across three companion files, rewrite the whole thing: it is just SKILL.md. Treat the builder as a scaffolding step. After it runs, you own the artifact the same way you would own anything you hand-typed.
Testing your skill once you have one
Two tests cover most of the failure modes. Start with the direct invocation.
Open Claude Code in a project where the skill applies. Type /<your-skill-name> and pass it whatever input it expects. Claude loads the body verbatim and runs the instructions. Read the output critically. The most common failure mode is instructions that are clear to a human and ambiguous to Claude, which usually means the skill assumes context the model does not have. Add it.
The second test is the auto-invoke path. Close that session, start a new one, and ask the question the skill is supposed to handle, but phrased the way a real user would phrase it. Not "redline this MSA," more like "is this contract okay for us to sign." If Claude loads the skill on its own, your description is doing its job. If Claude answers from general knowledge and ignores the skill, your description does not match how people actually talk. Edit the description, restart, try again. This loop is where most of the iteration happens.
You can verify what Claude sees by asking it What skills are available? in a session. It will list the names and descriptions, so you can confirm yours is registered. The /doctor command surfaces whether your skill descriptions are getting truncated due to context budget, which becomes relevant once you have a dozen skills installed and they start competing for attention.
If the skill calls a script or runs a shell command, test that path explicitly. Injected context only works if the command runs cleanly on the machine where the skill lives. A skill that runs gh pr view breaks on a machine without gh installed, which is the kind of thing you learn the embarrassing way.
Sharing it
Three distribution paths, depending on the audience.
Commit the folder to a project repo under .claude/skills/<name>/. Anyone who clones the repo and trusts the workspace gets the skill automatically. This is the right move for team-specific procedures: the on-call runbook, the deploy checklist, the regulatory-review playbook.
Bundle related skills into a plugin. Anthropic's plugin documentation covers the packaging. Plugins make sense when you have, say, four skills that together form a contracts-review suite.
Publish to a public marketplace if you want an audience beyond your company. The Anthropic skills repo is the canonical reference set. SkillsMP indexes the broader public catalogue. There is room here. Most of what exists is engineering-adjacent. The shelves are conspicuously empty in regulated industries, in operations, in finance, in legal, in customer success. If you have ten years of expertise in any of those, your skill probably does not exist yet, and the audience for it does. The skill examples piece walks through fifteen working SKILL.md folders if you want to see what good looks like before you write.
Anthropic's own framing calls skills "specialized training manuals." A good one is the document you would hand a new hire on day one, except the new hire is an LLM already running in every Claude session your teammates open. Write it once. The value compounds with every invocation.
The remaining question is whether you have a procedure worth encoding. If you have read this far, you probably do.