How to Build Your Own Claude Skill from Scratch (Complete Guide)

Why Build Your Own Claude Skill?

The 36,000+ skills on DiscoverAISkills cover an enormous range of use cases, but they can't cover everything. Your workflow is unique. Your tools are specific. Your team has conventions that no generic skill will know about.

Building a custom skill solves this. Instead of explaining the same context to Claude every time you start a new conversation — "we use this internal tool, here's how it works, always format output this way" — you write it once as a skill file and Claude knows it automatically.

This guide walks through the complete process: from understanding the format to writing your first skill to testing and sharing it.

---

Understanding the SKILL.md Format

A Claude skill is a Markdown file, typically named SKILL.md, that lives in a specific folder. When Claude Code starts, it reads all skill files in ~/.claude/skills/ (personal) and .claude/skills/ (project-level) and adds their contents to its context.

The format is deliberately simple. There's no schema to follow, no required fields, no validation. A skill file is just instructions written in Markdown. Claude reads them and follows them.

That said, the best skill files share a common structure:

# Skill Name

Brief description of what this skill does and when to use it.

## Tools Available

Description of the tools or commands this skill provides access to.

## How to Use

Step-by-step instructions for common tasks.

## Guidelines

Rules and constraints Claude should follow when using this skill.

## Examples

Concrete examples of inputs and expected outputs.

You don't have to follow this structure exactly — but including these elements makes skills more reliable and easier to maintain.

---

Step 1: Define What Your Skill Does

Before writing a single line, answer these questions:

What problem does this skill solve? Be specific. "Helps with work" is not a skill. "Formats customer support tickets according to our internal template and assigns them to the right team based on category" is a skill.

What tools or commands does it use? Skills work by telling Claude how to use existing tools — CLI commands, APIs, file operations. If your skill doesn't use any external tools, it's probably just a prompt, not a skill.

When should Claude use this skill? Claude needs to know when to activate the skill. Include trigger phrases or conditions in your skill file.

What should Claude never do with this skill? Constraints are as important as capabilities. A skill that can send emails should probably confirm before sending.

---

Step 2: Write the Tool Descriptions

The most important part of any skill is the tool descriptions. Claude needs to know exactly what commands are available, what arguments they take, and what they return.

Here's an example for a hypothetical internal deployment tool:

## Available Commands

### deploy
Deploys a service to the specified environment.

./deploy.sh [--dry-run]


Arguments:
- service-name: The name of the service (e.g., "api", "frontend", "worker")
- environment: One of: staging, production
- --dry-run: Optional. Shows what would be deployed without actually deploying.

Returns: Deployment status, version deployed, and URL of the deployed service.

### rollback
Rolls back a service to the previous version.

./deploy.sh rollback


Use this only when explicitly asked to rollback. Always confirm before rolling back production.

Notice the level of detail: argument names, types, valid values, what the command returns, and a constraint (confirm before rolling back production). This specificity is what makes skills reliable.

---

Step 3: Write the Workflow Instructions

For multi-step tasks, write out the steps explicitly. Don't assume Claude will figure out the right order — tell it.

## Deployment Workflow

When asked to deploy a service:

1. Run `./deploy.sh <service> staging --dry-run` first to preview changes
2. Show the user the dry-run output and ask for confirmation
3. If confirmed, run `./deploy.sh <service> staging`
4. Wait for the deployment to complete and verify the health check passes
5. If staging looks good and the user asks to promote to production, repeat steps 1-4 with "production" instead of "staging"

Never deploy directly to production without first deploying to staging.

This kind of explicit workflow instruction is what separates a good skill from a great one. It encodes your team's best practices directly into Claude's behavior.

---

Step 4: Add Examples

Examples are the most underrated part of skill files. Claude learns from examples the same way humans do — seeing a concrete case makes abstract instructions much clearer.

## Examples

**User:** Deploy the API to staging
**Claude should:** Run `./deploy.sh api staging --dry-run`, show the output, ask for confirmation, then run the actual deployment.

**User:** What version of the frontend is running in production?
**Claude should:** Run `./deploy.sh status frontend production` and report the version from the output.

**User:** The API is broken in production, roll it back
**Claude should:** First ask "Are you sure you want to roll back the API in production? This will revert to the previous version." Then, if confirmed, run `./deploy.sh rollback api production`.

---

Step 5: Install and Test Your Skill

Create the skill directory and file:

mkdir -p ~/.claude/skills/my-deploy-tool
nano ~/.claude/skills/my-deploy-tool/SKILL.md

Paste your skill content, save, and restart Claude Code.

Now test it systematically:

Test the happy path: Ask Claude to do the most common task the skill is designed for. Does it use the right commands? Does it follow the workflow?

Test edge cases: What happens when you give it an invalid argument? Does it handle errors gracefully?

Test the constraints: Ask Claude to do something the skill says it shouldn't do. Does it refuse or ask for confirmation?

Test with ambiguous input: Give Claude a vague request and see if it asks the right clarifying questions.

Keep a log of what works and what doesn't. You'll iterate on the skill file several times before it's reliable.

---

Common Mistakes to Avoid

Being too vague about tool syntax. "Use the deploy script" is not enough. Claude needs the exact command, arguments, and expected output format.

Forgetting error handling. What should Claude do when a command fails? If you don't specify, it will improvise — sometimes well, sometimes not.

No constraints on destructive operations. Any skill that can delete, overwrite, or send data should have explicit confirmation requirements for irreversible actions.

Too many responsibilities in one skill. A skill that does 15 different things is hard to maintain and harder for Claude to use correctly. Split complex skills into focused ones.

Not testing with real tasks. Skills that look good on paper often have gaps that only show up in real use. Test with actual tasks from your workflow.

---

Advanced Techniques

Conditional Behavior

Skills can include conditional logic in plain language:

## Environment Rules

- In development: run commands directly, no confirmation needed
- In staging: show dry-run output first, then ask for confirmation
- In production: always require explicit confirmation, log all actions

Referencing Other Skills

Skills can reference other skills:

## Prerequisites

This skill requires the GitHub skill to be installed. Use it to create issues for deployment failures.

Dynamic Context

Skills can tell Claude to gather context before acting:

## Before Deploying

Always check the current deployment status with `./deploy.sh status <service> <environment>` before making changes. Include this status in your response.

---

Sharing Your Skill

If your skill would be useful to others, consider submitting it to DiscoverAISkills. The submission process is straightforward: provide the skill file, a description, and the install instructions.

Skills that get the most installs tend to:

Solve a specific, common problem
Work with widely-used tools (GitHub, Notion, Slack, etc.)
Have clear, well-written documentation
Include examples that make the use case obvious

The Skill Creator skill — which helps Claude write new skill files based on your description — is a useful starting point if you're not sure how to structure your skill. It's essentially a skill for building skills.

---

The Skill Creator Shortcut

If writing a skill from scratch feels daunting, there's a shortcut: install the Skill Creator skill and describe what you want to Claude in plain language.

npx clawhub@latest install skill-creator

Then tell Claude: "I want to create a skill for our internal deployment tool. It uses a script called deploy.sh with these arguments..." Claude will draft the skill file for you, which you can then refine.

This is how many of the community skills on DiscoverAISkills were created — not by writing Markdown from scratch, but by describing the use case to Claude and iterating on the output.

---

What to Build Next

The best skills to build are the ones that solve your specific pain points. Start by noticing when you're giving Claude the same instructions repeatedly — that's a skill waiting to be written.

Browse DiscoverAISkills to see what already exists before building from scratch. With 36,000+ skills in the catalog, there's a good chance someone has already solved your problem. If not, build it — and consider sharing it so others can benefit too.