How to Write Your First Claude Code Skill (SKILL.md Guide)

Stop typing the same sequence of git add, npm test, and git commit over and over again. This tutorial shows you how to build your first Claude Code skill—a /smart-commit command that handles linting, diff reviews, and conventional commit messages in one autonomous step. By the end of this guide, you’ll have a custom SKILL.md file that you can share with your team or publish to the community. It’s time to turn your terminal assistant into a specialized agent that knows exactly how your project needs to be handled.

What do I need to have installed before I start?

You need Claude Code installed globally via npm and a git repository where you can test your new skills. You also need a basic understanding of Markdown, as that’s how you’ll be writing the instructions for your agent.

The Scenario: You’re sitting at your desk, ready to automate your workflow, but you realize you don’t even have the right CLI tools installed yet. You spend five minutes getting Claude Code set up so you can finally stop doing the “boring” parts of your job manually.

Where should I store my custom Claude skills?

A skill lives in a directory inside your project’s .claude/skills/ folder. This keeps your automation local to the project so that anyone else on your team can use it as soon as they clone the repo.

The Scenario: You’ve written a great automation, but your coworker can’t use it because it’s only on your machine. You realize you need to move it into the project’s folder so the whole team can benefit from your “laziness.”

How do I write the instructions for my first skill?

The SKILL.md file is where you define the steps Claude should take. You use plain English to describe the workflow: “Step 1: Check for changes. Step 2: Run lint. Step 3: Write a commit message.” Claude interprets these instructions and executes the corresponding shell commands.

The Scenario: You’re trying to explain to a junior dev how to commit code properly. You realize you can just write those same instructions into a SKILL.md and let the AI handle it instead of repeating yourself every week.

How do I actually run my new slash command?

Once your SKILL.md is saved, you can run the command directly in Claude Code by typing your trigger, like /smart-commit. Claude will walk through your steps, show you what it’s doing, and ask for confirmation before it makes any permanent changes like a git commit.

The Scenario: You’ve just finished a big feature. You type /smart-commit. You watch as the AI lints your code, finds a typo, fixes it, and then proposes a perfect commit message. It feels like you’ve just hired a tiny, very efficient assistant.

How do I add logging or notifications to my skill?

You can use lifecycle hooks to add extra functionality. For example, a before_start hook can log the current date to a file, or an after_success hook can send a notification to your Slack channel. It makes your skills feel like a professional part of your pipeline.

The Scenario: You want to keep track of how many times you’re using AI to commit code. You add a hook that appends every successful commit to a log file. At the end of the month, you’re shocked to see the AI handled 200 commits for you.

Add a skills.json to your project root. This tells Claude Code where to find the skills in your repo. When your teammates run claude skills sync, they’ll get all your custom commands instantly. No more manual setup for the rest of the team.

The Scenario: Your lead dev is impressed by your /smart-commit command. They want it for the whole team. You add the skills.json and five minutes later, everyone is shipping code faster and more consistently.

How do I let other developers use my Claude skills?

To go public, create a GitHub repo for your skill and add a skill.json manifest. Other developers can then install it with a single command. It’s the best way to contribute to the growing ecosystem of AI-powered developer tools.

The Scenario: You’ve built a skill that perfectly automates a complex AWS deployment. You realize other people are struggling with the same thing. You publish it to GitHub and suddenly you’re getting “stars” from developers all over the world.

What else can I build once I’ve mastered the basics?

Once you understand the numbered instruction pattern, you can build skills for anything: automated test runners, documentation generators, or even a /review-pr command that summarizes the changes in a pull request. The terminal is your playground.

The Scenario: You’re bored on a Friday afternoon. You decide to build a /clean-logs skill that finds every console.log in your app and comments it out. You realize you’ve just saved yourself twenty minutes of manual cleanup for every future PR.

What are the most common mistakes when writing skills?

The most common mistake is being too vague. Claude follows instructions literally, so if you don’t tell it to “stop and show errors if lint fails,” it might just keep going and commit broken code. Be explicit, be numbered, and always include checkpoints.

The Scenario: You wrote a skill that’s supposed to deploy your app, but it forgot to check if the tests passed first. You just deployed a broken build to production. You go back to your SKILL.md and add a very loud, clear instruction to “STOP ON TEST FAILURE.”