Skip to main content

Creating Custom Skills

Module: Skills | Lesson: 3 of 3 | Time: ~10 minutes

What You Will Learn​

  • How to create a custom skill in .claude/skills/
  • The structure and format of a skill file
  • How to define triggers so your skill activates

Prerequisites​

Creating Your First Custom Skill​

Custom skills are Markdown files that you write and place in your project's .claude/skills/ directory. Once they are there, Claude discovers them automatically and follows the instructions they contain.

Let us walk through the entire process of creating a custom skill from scratch.

Step 1: Create the Skills Directory​

If your project does not already have a skills folder, create one:

mkdir -p .claude/skills
Windows Command Prompt

If you are using the standard Windows Command Prompt instead of PowerShell or WSL, use:

mkdir .claude\skills

Step 2: Create a Skill File​

A skill file is a plain Markdown file. Create a new file inside .claude/skills/. The filename should describe what the skill does:

# Example filenames:
#   .claude/skills/coding-standards.md
#   .claude/skills/deploy-to-staging.md
#   .claude/skills/pr-review-checklist.md

Step 3: Write the Skill Content​

Every skill file has two parts: frontmatter at the top and instructions in the body.

Frontmatter​

The frontmatter is a YAML block at the very top of the file, enclosed in --- lines. It tells Claude metadata about the skill:

---
title: Deploy to Staging
description: Step-by-step process for deploying the app to the staging environment
triggers:
  - deploy
  - staging
  - release
---

Here is what each field does:

FieldRequiredPurpose
titleYesA short name for the skill
descriptionYesWhat the skill does — helps Claude decide when to use it
triggersNoKeywords that help Claude recognize when this skill is relevant

Instructions Body​

After the frontmatter, write your instructions in plain Markdown. Be clear and specific — Claude will follow these instructions literally:

---
title: Deploy to Staging
description: Step-by-step process for deploying the app to the staging environment
triggers:
  - deploy
  - staging
  - release
---

# Deploy to Staging

Follow these steps exactly when deploying to the staging environment:

1. Run the test suite first:
   ```bash
   npm test
  1. If all tests pass, create a production build: 
    npm run build
  2. Deploy to the staging server: 
    npm run deploy:staging
  3. After deployment, verify the staging URL responds: 
    curl -I https://staging.example.com
  4. Report the deployment status and the staging URL.

Important Rules​

  • NEVER deploy if any tests fail
  • ALWAYS verify the staging URL after deployment
  • If any step fails, stop and report the error

## How Triggers Work

The `triggers` field in the frontmatter is a list of keywords. When your conversation with Claude includes these words, Claude is more likely to recognize that the skill is relevant and follow its instructions.

For example, if your skill has `triggers: [deploy, staging]` and you ask Claude "Can you deploy this to staging?", Claude will match those keywords and apply the skill's instructions.

:::note
Triggers are hints, not strict rules. Claude uses them along with the skill's description and the overall conversation context to decide whether to apply a skill. Even without triggers, Claude may use a skill if the description matches what you are asking for.
:::

## Tool Restrictions in Skills

You can optionally restrict which tools Claude is allowed to use when following a skill. This is useful for safety — for example, a "review" skill might be restricted to read-only tools:

```markdown
---
title: Code Review Checklist
description: Review code changes against our team standards
triggers:
  - review
  - code review
allowed_tools:
  - Read
  - Grep
  - Glob
---

With allowed_tools specified, Claude will only use those tools when executing this skill. It will not edit files, run commands, or make changes.

A Complete Example: PR Description Skill​

Here is a practical skill that generates pull request descriptions:

---
title: Write PR Description
description: Generate a pull request description from the current branch changes
triggers:
  - pr description
  - pull request
  - pr
---

# Write PR Description

When asked to write a PR description:

1. Run `git diff main...HEAD` to see all changes on this branch
2. Run `git log main..HEAD --oneline` to see all commits
3. Write a PR description with these sections:

## Format

What Changed​

(2-3 sentence summary of the changes)

Why​

(Brief explanation of the motivation)

How to Test​

(Steps a reviewer can follow to verify)

Checklist​

  • Tests pass
  • No console.log statements left
  • Documentation updated if needed

4. Output the description so I can copy it.

Try It Yourself​

Create a simple coding standards skill for a test project:

  1. Navigate to a project folder (or create one) and set up the skills directory:
mkdir -p my-project/.claude/skills
cd my-project
  1. Create a file called .claude/skills/coding-standards.md with this content:
---
title: Coding Standards
description: Our team's coding conventions and style rules
triggers:
  - style
  - standards
  - conventions
---

# Coding Standards

When writing or modifying code in this project, follow these rules:

- Use 2-space indentation (no tabs)
- Use camelCase for variable names
- Use PascalCase for class names
- Every function must have a brief comment explaining its purpose
- Keep functions under 30 lines when possible
  1. Start Claude Code in the project directory:
claude

  1. Ask Claude to create a small JavaScript file. Notice whether it follows your coding standards (2-space indent, camelCase, comments on functions).

  2. Then ask: "Does this file follow our coding standards?" Claude should reference your skill to check.

What You Learned​

  • Custom skills are Markdown files placed in .claude/skills/
  • Each skill has frontmatter (title, description, triggers) and an instructions body
  • Triggers are keywords that help Claude match the skill to your request
  • You can restrict which tools a skill is allowed to use with allowed_tools
  • Claude auto-discovers skills on startup — just drop the file in the right folder and it works
Help Us Improve

How was this lesson? Take 2 minutes to share your feedback — it helps us make the tutorials better for everyone.

Give Feedback →

Next Up​

Next: Capstone: Create a Custom Skill