How to Build a Claude Code Skill in 7 Steps

Every developer has workflows they repeat daily—code reviews, commit messages, pull request checklists. But explaining these workflows to AI agents manually leads to inconsistent results. Agent skills solve this by encoding workflows into structured markdown files. This guide shows you how to build a Claude Code skill that generates structured commit messages following the Conventional Commits standard.

What Is a Claude Code Skill?

A skill is a folder containing a SKILL.md file with two parts:

YAML frontmatter (metadata about the skill)
Markdown body (instructions for the agent)

The structure looks like this:

my-skill/
└── SKILL.md

The frontmatter defines the skill’s name and description. The body contains actionable instructions. When you invoke a skill using /skill-name, the agent loads the instructions and executes them.

Step 1: Choose a Workflow to Automate

Good skills share three traits:

Repeatable: You follow the same steps every time
Structured output: Produces a fixed format (commit message, code review, etc.)
Clear trigger: You can finish the sentence “I need this skill when I want to…”

For this tutorial, we’ll build a commit-message-writer skill that:

Reads staged changes
Applies Conventional Commits format
Generates a structured commit message

Step 2: Structure Your Skill Folder

Create a folder with a SKILL.md file:

commit-message-writer/
└── SKILL.md

Keep the SKILL.md body under 500 lines. For complex skills, add supporting files in a references/ subfolder and reference them in your instructions.

Step 3: Write a Strong Description

The description determines when your skill loads. Use this pattern:

What the skill does + when to use it + trigger phrases

Example:

Generates structured commit messages following the Conventional Commits standard. Use when you want to commit your changes and need a well-formatted message. Triggers on “write a commit message”, “commit my changes”, or “summarize my staged diff”.

Step 4: Define Clear Instructions

Follow these principles:

Generate first: Produce output immediately without asking clarifying questions
Explicit format: Define the output structure precisely

Example instruction for commit message generation:

Analyze the staged changes. Generate a commit message with:
Type prefix (feat, fix, docs, etc.)
Scope in parentheses
Short subject line
Optional body with detailed changes

Step 5: Test and Refine

Test your skill by:

Using the /commit-message-writer command
Describing your request in natural language
Checking if the output matches your expectations

Improve your skill by:

Adding examples in a references/examples.md file
Expanding trigger phrases in the description
Refining the output format based on feedback

Step 6: Share Your Skill

Skills follow an open standard and work across platforms including:

Claude Code
GitHub Copilot
Cursor
Gemini CLI

Share your skill by:

Pushing it to a public GitHub repository
Adding it to the Claude Skills Registry
Sharing the folder directly with your team

Step 7: Build More Skills

Once you’ve mastered the basics, try building skills for:

Pull request descriptions
Code reviews
Changelog entries
API documentation

Start Building Your First Skill Today

Automate your most common workflows with Claude Code skills. By encoding your workflows into structured markdown, you’ll save time, reduce errors, and ensure consistency across your development process. Start with a simple commit message generator and expand to more complex skills as you gain confidence.

Ready to build your first skill? Create a commit-message-writer folder and start writing your SKILL.md file today.