How to Create Your Own SKILL.md File from Scratch

Every developer has workflows they repeat. Writing test boilerplate, scaffolding components, reviewing PRs, setting up CI configs. These are exactly the tasks that make great skills. This tutorial walks through creating a SKILL.md file from scratch, testing it, and making it good enough to share.

What you need

A text editor. That's it. Skills are markdown files. No build tools, no dependencies, no compilation step.

You'll also need Claude Code (or another agent that supports SKILL.md) to test your skill. But the writing part is just editing a text file.

Step 1: Pick a task

Start with something you do at least once a week. The best first skills are tasks that are repetitive but not trivial. You want something where the output needs to be accurate and follow a specific pattern.

Good first skills: writing commit messages, generating component boilerplate, reviewing code against a checklist, creating PR descriptions, writing test scaffolding.

Bad first skills: anything highly creative with no defined output format, or anything so simple that a one-line prompt already handles it.

Step 2: Create the folder

Skills live in folders. Create one in your skills directory:

mkdir -p ~/.claude/skills/my-skill

Then create the SKILL.md file inside it:

touch ~/.claude/skills/my-skill/SKILL.md

Step 3: Write the frontmatter

Open SKILL.md in your editor and add the frontmatter block at the top:

---
name: my-skill
description: Describe what this skill does and when the agent 
  should use it. Be specific about trigger phrases.
---

The name field becomes the /slash-command you can type to invoke the skill. Use lowercase with hyphens.

The description field is critical. This is what the agent reads to decide whether to load your skill automatically. Be explicit about trigger phrases. Instead of "helps with testing," write "Generates unit test boilerplate for React components. Use when the user asks to write tests, add test coverage, or mentions testing."

Optional frontmatter fields

context: fork makes the skill run as a subagent with its own isolated context. Use this for skills that do significant independent work.

disable-model-invocation: true prevents the agent from loading the skill automatically. The user must invoke it manually with /skill-name. Good for skills with side effects like deploying or sending messages.

Step 4: Write the instructions

Below the frontmatter, write your instructions in markdown. This is the playbook the agent follows.

Structure your instructions as clear, numbered steps. Include specific details about what to check, what to output, and how to format results.

Here's an example for a test scaffolding skill:

# Test Scaffolding

When asked to create tests for a file or component:

1. Read the source file to understand its exports, props, and behavior
2. Identify the testing framework in use (check package.json for 
   jest, vitest, mocha, or playwright)
3. Create a test file following the project's naming convention:
   - If existing tests use .test.tsx, use that pattern
   - If existing tests use .spec.ts, use that pattern
   - If no pattern exists, default to [filename].test.ts
4. Write tests covering:
   - Happy path for each exported function or component
   - Edge cases (null inputs, empty arrays, boundary values)
   - Error cases (invalid inputs, failed network calls)
5. Use the project's existing test utilities and helpers if present
6. Match the assertion style used in existing tests

## Output format

Each test should have a descriptive name that explains what it verifies.
Group related tests in describe blocks.
Include comments explaining non-obvious test logic.

Tips for good instructions

Be specific, not general. "Check for bugs" is vague. "Check for null pointer exceptions, unhandled promise rejections, and array index out of bounds errors" gives the agent clear targets.

Include output format examples. If you want findings organized by severity, show what that looks like.

Handle edge cases. Add instructions for when the expected input isn't present. "If no package.json exists, ask the user which testing framework to use."

Keep it under 500 lines. If your instructions are longer, move detailed reference material to a references/ folder and link to it.

Step 5: Add supporting files (optional)

For simple skills, a single SKILL.md is enough. For more complex skills, you can add supporting files:

my-skill/
├── SKILL.md           # Required
├── scripts/           # Helper scripts the skill can run
├── references/        # Additional docs loaded on demand
└── assets/            # Templates, config files, examples

Your SKILL.md can reference these files in its instructions. For example: "Load the style guide from references/style-guide.md before reviewing."

Step 6: Test it

Start a new Claude Code session and try your skill:

claude

First, test manual invocation:

/my-skill

The agent should load your instructions and follow them. If it doesn't respond to the slash command, check that your folder is in the right location and the SKILL.md file has valid frontmatter.

Then test automatic invocation. Ask the agent something that matches your skill's description without mentioning the skill name. If the description is well-written, the agent should pick it up.

If it doesn't trigger automatically, refine the description. Add more trigger phrases and make them match how you'd naturally ask for the task.

Step 7: Iterate

Your first version won't be perfect. Use it for a few days and notice where the output isn't what you want. Then update the instructions.

Common improvements after the first version: adding edge case handling, specifying output format more precisely, adding examples of good and bad output, narrowing the trigger description to avoid false activations.

Step 8: Share it

If your skill works well, other developers will find it useful too. You have a few options:

Publish on GitHub. Push the skill folder to a public repo. Other developers can clone it or add it as a plugin marketplace.

Submit to Agensi. Package your skill as a zip file and submit it on Agensi. Your skill goes through a security review and gets listed in the marketplace for other developers to find.

Share with your team. Put the skill folder in .claude/skills/ inside your project repo. Every developer who clones the project gets the skill automatically.

For the full SKILL.md specification and advanced features, read our complete guide to SKILL.md.