How to Write Skills for Claude Code and Cowork

By the Sherlock team · March 10, 2026 · 6 min read

A skill is a markdown file that teaches Claude how to do something. You write a SKILL.md, put it in the right folder, and Claude either picks it up automatically when it's relevant or you invoke it with a slash command. Skills work across both Claude Code and Cowork, and they follow the open Agent Skills standard, which means they're portable to other compatible tools too. This guide gets you from zero to a working skill in about ten minutes.

Anatomy of a Skill

Every skill is a folder containing a SKILL.md file. That file has two parts: YAML frontmatter at the top (between --- markers) that tells Claude metadata about the skill, and markdown content below it with the actual instructions. Here's the simplest possible skill:

That's it. The name becomes the slash command (/explain-code), the description tells Claude when to load it automatically, and the markdown body is what Claude follows when the skill is active. You can also bundle supporting files — scripts, templates, reference docs, example outputs — in the same directory, and reference them from the SKILL.md so Claude knows when to pull them in.

Where Skills Live

Where you put a skill determines who can use it. Personal skills at ~/.claude/skills/your-skill/ are available across all your projects. Project skills at .claude/skills/your-skill/ apply to that repo only and can be committed to version control so your whole team gets them. Plugin skills live inside a plugin's skills/ directory and use a namespaced format like plugin-name:skill-name. Enterprise skills are deployed organization-wide through managed settings. When skills share a name, higher-priority locations win: enterprise > personal > project.

Writing a Good Description

The description is the most important line in your skill. Claude uses it to decide whether to load the skill automatically based on the conversation, so a vague description means Claude won't trigger it when it should. The official docs are explicit about this: Claude has a tendency to undertrigger skills, so you want to make descriptions slightly "pushy." Instead of writing Generates a deployment checklist, write something like Generates a deployment checklist. Use whenever the user mentions deploying, launching, shipping, going to production, or asks about release readiness — even if they don't explicitly ask for a checklist. Keep the description concise but thorough about trigger conditions — you're competing for context budget, so every word should either explain what the skill does or when Claude should reach for it.

Frontmatter Reference

Beyond name and description, the frontmatter supports several fields that control how your skill behaves. You won't need most of these for simple skills, but they unlock powerful patterns as you get more advanced.

The three you'll use most often: disable-model-invocation: true for anything with side effects (deployments, commits, Slack messages) where you want to control timing. allowed-tools to grant specific tool access without per-use approval. And context: fork to run the skill in an isolated subagent that doesn't have access to your conversation history — useful for research tasks, parallel analysis, or anything you want sandboxed.

Arguments and Dynamic Context

Skills can accept arguments. Use $ARGUMENTS in your skill content as a placeholder for everything the user types after the skill name. Running /fix-issue 123 on a skill that contains Fix GitHub issue $ARGUMENTS gives Claude Fix GitHub issue 123. You can also access individual arguments by position with $0, $1, $2 (or the longer $ARGUMENTS[0] form).

For dynamic context that needs to be fetched before Claude sees the skill, use the ! backtick syntax to run shell commands during preprocessing. The command output replaces the placeholder, so Claude receives real data, not the command itself:

When this skill runs, each ! backtick command executes immediately, the output gets inserted into the skill content, and Claude receives a fully-rendered prompt with actual PR data.

Build a Skill in 5 Minutes

Here's a practical example: a skill that generates a security checklist for a smart contract before deployment. This one uses arguments, references a bundled template, and restricts tool access.

Write ~/.claude/skills/pre-deploy-check/SKILL.md:

Test it by opening Claude Code in a project with Solidity contracts and typing /pre-deploy-check contracts/. Claude reads the contracts, runs the checks, compiles, tests, and outputs a structured report. The allowed-tools field means it won't ask permission for each file read or grep — it just executes.

Tips From Writing Skills in Production

Keep SKILL.md under 500 lines. The official docs recommend this explicitly. If your skill needs detailed API specs, long reference tables, or extensive examples, move them to separate files in the skill directory and reference them from SKILL.md. Claude will read them when needed without bloating every invocation.

Include examples of what good output looks like. If your skill generates a report, put a sample output in examples/sample-output.md and reference it. Claude calibrates its output quality and format to match the examples it sees, so a concrete example is worth more than a paragraph of formatting instructions.

Use disable-model-invocation: true for anything destructive. Deployments, git operations, sending messages, deleting files — anything where you want to control timing rather than letting Claude decide. You can still invoke it manually with /skill-name, but Claude won't fire it because your conversation happened to mention "deploying."

Test with context: fork for expensive skills. If your skill runs a long analysis, spawns subagents, or generates large outputs, running it in a forked context keeps it from polluting your main conversation. The results get summarized and returned to your session. Pair it with agent: Explore for read-only research tasks.

Commit project skills to version control. Skills in .claude/skills/ can be committed so your whole team gets them when they pull. This is the easiest way to standardize workflows across a team — everyone gets the same /pre-deploy-check or /generate-tests without installing anything.

Use the skill-creator skill to iterate. If you have Claude Code or Cowork open, type /skill-creator and describe what you want. It will interview you about the use case, write a draft, generate test prompts, run them, and help you evaluate and iterate. It's the fastest way to go from idea to polished skill, especially if you're not sure how to phrase the instructions.

Quick Reference

Claude Skills - Frequently Asked Questions

What is a Claude skill?

A markdown file (SKILL.md) that gives Claude instructions it can follow when relevant. Skills can be reference knowledge, task playbooks, or full workflows with bundled scripts. You invoke them with /skill-name or let Claude load them automatically. They follow the open Agent Skills standard and work across Claude Code, Cowork, and other compatible tools.

How do I create my first skill?

Create a folder at ~/.claude/skills/your-skill-name/, add a SKILL.md with YAML frontmatter (name + description) and markdown instructions, and you're done. Test it with /your-skill-name or by asking Claude something that matches the description.

Do skills work in both Claude Code and Cowork?

Yes. Same SKILL.md format, same frontmatter, same behavior. Skills written for one work in the other. In Cowork, you can also discover and install community skills through the plugin directory.

Where should I put my skill files?

Personal skills at ~/.claude/skills/ work across all your projects. Project skills at .claude/skills/ apply to that repo only (commit them to share with your team). Plugin skills use a namespaced plugin-name:skill-name format.

Why isn't Claude triggering my skill?

Almost always the description. Make it more specific about trigger conditions, and slightly "pushy" — list the phrases and contexts where Claude should use it, even if the user doesn't explicitly ask. Check that the skill appears when you ask Claude "What skills are available?" If you have many skills, they may exceed the description context budget (2% of context window).

How do I pass arguments to a skill?

Use $ARGUMENTS in your SKILL.md for all arguments, or $0, $1, $2 for positional access. Running /fix-issue 123 replaces $ARGUMENTS with 123. If $ARGUMENTS isn't in the skill content, arguments are appended automatically.

‍