Build Your First AI Agent Skill in 10 Minutes — From Empty Folder to Working Capability

Building a skill from scratch sounds intimidating until you do it. The first one takes about 10 minutes and requires zero code — just a folder and a markdown file. Here is exactly how.

The first skill almost everyone builds is markdown-only — no scripts, no dependencies, no infrastructure. Just instructions in a file that the agent reads and follows. This pattern works for an enormous range of useful capabilities, and it is the right place to start before adding any complexity.

Pick Something You Do Repeatedly

The best first skill is one that automates something you find yourself doing manually over and over. Common picks: writing commit messages in a specific format, drafting customer email replies in your style, formatting meeting notes, creating bug reports, generating PR descriptions. Anything where you have an internal "how I do this" pattern that you wish the agent would apply automatically.

For this walkthrough, we will build commit-message-writer — a skill that writes conventional commit messages following the Conventional Commits specification.

Step 1: Create the Folder

The folder name becomes the skill identifier:

mkdir -p ~/.claude/skills/commit-message-writer
cd ~/.claude/skills/commit-message-writer
touch SKILL.md

Step 2: Write the YAML Frontmatter

Open SKILL.md and add the required metadata:

---
name: commit-message-writer
description: Writes conventional commit messages following
  the Conventional Commits specification. Use when the user
  asks for a commit message, when committing changes, or
  whenever git commit operations are involved.
version: "1.0.0"
---

The description is the most important field. Notice it does three things: states what the skill does ("writes conventional commit messages"), specifies when to use it ("when the user asks for a commit message"), and includes implicit triggers ("whenever git commit operations are involved"). This matches how users actually ask for commit messages — with explicit phrasing, with implicit phrasing, and during related operations.

Step 3: Write the Instructions

Below the closing dashes, write what the agent should do when this skill triggers:

# Commit Message Writer

## Instructions

Write commit messages in Conventional Commits format:

    type(scope): description

Required types: feat, fix, docs, style, refactor, test, chore.
Description is imperative mood, lowercase, no period.
Maximum 72 characters in the first line.

## Examples

- feat(auth): add OAuth2 login support
- fix(api): handle null user IDs in profile endpoint

## Guidelines

- Never use past tense — always imperative
- Never end the description with a period
- If breaking change, add BREAKING CHANGE: footer

Step 4: Test It

Restart Claude Code (or your agent). Ask: "Write me a commit message for adding email verification to the signup flow." The agent reads the description, matches your request, loads the instructions, and produces something like: feat(auth): add email verification to signup flow.

That is the entire process. About 10 minutes from empty folder to working capability. Once you have built one skill, every subsequent skill follows the same pattern with slight variations — add a scripts/ folder for shell or Python logic, add a REFERENCE.md for detailed documentation, add API call patterns for external integrations.