How to write your first SKILL.md from scratch

The most common mistake people make writing their first skill: trying to build a complete operating system.

A good skill is usually smaller than you expect. It’s a reusable workflow for one specific job — not a personality transplant for your agent.

Pick one repeated task. Just one.

Something you do often enough that inconsistent output actually costs you:

• Writing proposals for clients
• Reviewing pull requests for specific issues
• Summarizing customer interviews
• Planning blog outlines with keyword research

That’s your target. Not a grand framework. Not a comprehensive system. One task, done reliably, same quality every time.

If you’re not sure which task to pick: where do you get the most inconsistent output from your agent, even when you describe the task carefully? That inconsistency is your signal. A structured process would fix it.

What a useful skill actually does

Four things. Not more.

1. Defines the task — what kind of work this skill handles and when to use it
2. Names the inputs — what you need to provide before the agent can start
3. Gives a repeatable process — the actual steps, in order
4. Defines the output shape — what the finished thing looks like

That’s it. The best skills feel boring when you first read them. Mostly clarity and sequence. That’s the point. Inspiration belongs in creative briefs. Process belongs in skills.

The skeleton

Start here. Don’t invent a new format.

# Skill Name

## Purpose
One or two sentences. What does this skill handle?

## When to use it
Specific situations where this skill applies.

## Inputs needed
What must the user provide before the agent starts?

## Process
Step-by-step. Be specific about order.

## Output format
What does the finished deliverable look like?

That structure covers most straightforward workflows without adding overhead. Use it until you have a real reason to deviate.

A concrete example

Here’s a PR review skill following the skeleton:

# PR Review

## Purpose
Review a pull request for correctness, clarity, and potential issues.

## When to use it
When reviewing a pull request before approving or requesting changes.

## Inputs needed
- The diff or changed files
- The PR description and linked ticket (if any)
- Any relevant codebase conventions

## Process
1. Read the PR description — understand the stated intent
2. Check the diff for logic errors, edge cases, and test coverage
3. Check naming, readability, and inline documentation
4. Flag anything that conflicts with stated conventions
5. Summarize findings by severity: blocking, suggested, optional

## Output format
Short summary paragraph, then three sections:
- Blocking issues (must fix before merge)
- Suggestions (would improve the code)
- Optional notes (low-priority observations)

Short. Specific. Executable. Someone could follow those instructions without Claude.

What kills first skills

Too broad. “Help me with code” is a prompt, not a skill. Skills describe a specific, repeatable job.

Too many steps. If your process has 20 steps for a 15-minute task, it creates more overhead than value. Cut anything that doesn’t meaningfully change the output.

No output format. Without a defined shape, the agent produces something different every time. Even one line helps: “respond in bullet points grouped by priority.”

Vague inputs. If the skill needs inputs but doesn’t name them, the agent guesses. And guessing is inconsistent by definition. Name the inputs explicitly.

Writing for the model instead of the task. Don’t optimize your wording for perceived model preferences. Write clearly for a human reader. If a person could follow your instructions, Claude can too.

Read real skills before writing your own

The fastest path to a good first skill is reading five or six existing ones. Every skill on findskills.co shows the full raw SKILL.md on its detail page.

Specifically: read Skill Creator. It’s Anthropic’s own skill for writing skills. The format is exactly what agents expect, and it shows you what scope and depth look like in practice.

Test it on real work before you ship it

Three examples from your actual backlog. Not hypotheticals — real tasks.

You’ll quickly find where the instructions are too vague, too rigid, or missing edge cases. First versions always have at least one gap. That’s fine. The point of testing is to find it before you’re relying on the skill in production.

Check specifically:

• Does the agent ask for the inputs you named, or assume and guess?
• Does the output format match what you described?
• Does any step get interpreted differently each run?

When it’s stable across three real cases, use it yourself for a few weeks. Share it only after you trust it. The skills worth listing in any directory are the ones someone built for their own repeated problem — not the ones someone wrote to fill a gap they imagined.

Once it’s solid, submit it to findskills.co. If it clears source verification, it’ll be listed alongside Anthropic’s and Composio’s skills.