A working Claude Code skill needs three things: a name field, a description that tells Claude when to use it, and a body with instructions. Eight lines. Three minutes if you type quickly. The example below generates conventional commit messages and works exactly as written. GitHub developers pushed nearly 1 billion commits in 2025, up 25% year-over-year (GitHub Octoverse, 2025). Commit messages are among the most repeated developer actions in any codebase, which makes them the highest-value target for a first skill.

TL;DR: A minimum-viable Claude Code skill is 8 lines: two frontmatter fields and a few sentences of instructions. Build the commit message skill below, drop it in .claude/skills/commit-message/SKILL.md, and it works. Add complexity later only if the basic version breaks. This is the AEM standard for every first skill we build.

This is the full SKILL.md:

---
name: commit-message
description: "Use when the user asks for a git commit message, wants to commit changes, or runs a commit command. Generate a conventional commit message from the staged diff."
---

# Commit Message Generator

Read the staged git diff and write a conventional commit message.
Format: `type(scope): subject` where type is feat, fix, docs, style, refactor, test, or chore.
Keep the subject under 72 characters. No period at the end.

Create the folder .claude/skills/commit-message/, put that content in SKILL.md, open a new Claude Code session, stage some changes, and type "write a commit message." Claude reads the diff and writes the message. The skill is a prompt you don't have to type again.

Why Does This Work with So Few Lines?

The description field handles routing. Claude Code reads every installed skill's description at startup and uses it to decide which skill to activate. A description that names the exact user behavior gives Claude enough signal to route correctly. The instruction body handles execution: format, allowed types, length limit. Three lines cover all three.

"The failure mode isn't that the model is bad at the task — it's that the task wasn't specified tightly enough. Almost every production failure traces back to an ambiguous instruction." — Simon Willison, creator of Datasette and llm CLI (2024)

Three lines of instruction is not too few if the task is well-defined. "Write a conventional commit message under 72 characters" is a defined task. Claude already knows the conventional commits specification. You are not explaining the concept; you are providing the constraint.

Testing across 650 activation trials showed that imperative descriptions that name exact user behaviors achieve near-100% activation rates, while passive descriptions sit around 77% (Claude Code description field research, 2026). The description above names three exact trigger behaviors. That is the difference between a skill that activates reliably and one that activates inconsistently.

The repetition argument matters here. 87% of developers report that AI tools help them preserve mental effort on repetitive coding tasks (GitHub Copilot research, 2,000+ developers, GitHub 2024). A commit-message skill targets exactly that pattern: the same action, repeated dozens of times per week, now handled in one instruction.

For a deeper look at how descriptions control routing, see What Does the Description Field Do in a Claude Code Skill?.

What Are the Three Required Parts?

A minimum Claude Code skill requires three parts: a name slug, a one-line description that triggers routing, and a body with instructions. Together they total 8 lines. Reference files, evals, and learnings are optional. They add reliability over time, but none is a prerequisite for a working skill.

  • Name: the slug Claude Code uses for the slash command. name: commit-message means you can invoke it with /commit-message. It also appears in Claude's skill discovery.
  • Description: one line telling Claude when to use the skill. It must stay on one line in the frontmatter. The 1,024-character limit is generous; stay well under it. Multi-line descriptions are a common silent failure mode that breaks routing without any error message.
  • Body: everything after the closing --- of the frontmatter. This is what Claude reads when executing the skill. It can be two sentences or two hundred lines, depending on what the task requires.

Nothing else is strictly required for a first skill.

How Do I Install the Skill?

Drop the SKILL.md into a subfolder of .claude/skills/ relative to your project root, then open a new Claude Code session. No registration step is required. The presence of the file activates the skill automatically. The folder name should match the name field in the frontmatter by convention.

Create the folder and file:

mkdir -p .claude/skills/commit-message
# Create the SKILL.md file with the content above

Open a new Claude Code session in the same directory. Stage some changes with git add. Ask for a commit message.

The skill loads automatically at session startup. No registration step, no restart required. The presence of the SKILL.md file is the activation mechanism. Skills that exist in the directory are available; those that do not exist are not.

When Should I Add More to the Skill?

The right time to add complexity is after 10 real uses expose a failure. If the minimum-viable version handles the common case correctly on those 10 runs, it is reliable. If it fails, add the one instruction that would have prevented that specific failure. Nothing more.

A minimum skill won't handle tasks that require external API calls, stateful memory between sessions, or conditional branching across multiple outputs. Those needs require reference files and evals. The 8-line format is suited only for well-scoped, single-turn tasks where the input and output are both predictable.

Common additions after the minimum:

  • Scope naming conventions: "Use the directory name of the most-changed files as the scope."
  • Breaking change notation: "If any exported interface changes, add a footer BREAKING CHANGE: description."
  • Ticket linking: "If the branch name starts with PROJ-###, include that ID in the commit subject."

We run a minimum-viable-skill test on every commission before adding complexity. Strip the skill to the essentials, run it against 10 representative inputs, and confirm it works. Then add the edge-case handling. Skills built the other way, starting complex and hoping the basics work, fail on unexpected inputs far more often.

Developers using AI coding tools save an average of 3.6 hours per week (DX, 135,000+ developer sample, 2025). A well-scoped skill targeting one repeated action captures a disproportionate share of those savings. Start narrow.

A skill with 8 lines that handles the common case correctly is worth more than a 200-line skill with three untested branches.

What Is the Minimum Description That Still Routes Correctly?

The minimum description that routes reliably names the exact user behavior that triggers the skill and the output it produces. One sentence covering both is enough. A description that says only "Helps with commits" fails the first test. One that names the trigger behavior and the output format passes it.

Weak: "Helps with commits" Better: "Use when the user asks for a commit message or wants to commit staged changes" Best: "Use when the user asks for a git commit message, wants to commit, or runs a commit command. Generate a conventional commit message from the staged diff."

The best version names the exact user behaviors that trigger it and describes the output. This is the version worth 30 extra seconds to write. The conventional commit format the description references is already widespread: @commitlint/cli, the enforcement layer for the format, sees nearly 3 million weekly npm downloads (npm registry, 2025), indicating broad professional adoption. 51% of professional developers now use AI coding tools daily (Stack Overflow Developer Survey, 2025). For daily users, a weak description is a daily friction point.

For a hands-on walkthrough of building your first skill from scratch, see How Do I Create My First Claude Code Skill?.

FAQ

A minimum Claude Code skill works when the file is named correctly, placed in the right folder, and tested in a fresh session. Most activation failures trace back to one of these three setup conditions, not to the skill instructions themselves. The questions below address the specific failure modes developers encounter most.

Does the skill file need a specific filename?

The file must be named SKILL.md. The folder name can be anything, but by convention it matches the name field in the frontmatter. name: commit-message lives in a folder called commit-message.

What if my skill does nothing when I ask for a commit message?

Check two things: First, is the file at .claude/skills/commit-message/SKILL.md relative to your project root? Second, are you testing in a fresh Claude Code session opened after creating the file? Sessions started before the file existed do not pick up new skills automatically.

Can my minimum skill have a description longer than one line?

No. The description field must be a single-line YAML string. If it wraps to a second line, the second line becomes orphaned content outside the frontmatter. The skill may fail to route entirely, with no error message to indicate why.

How long until a minimum skill becomes a reliable one?

Most skills reach reliable status after 3-5 rounds of testing and iteration. Each round: run the skill against 5-10 representative prompts, note failures, add an instruction that covers the failure. Three rounds is enough for a well-defined task.

Can I copy community skills and use them as my minimum?

Yes. Installing a community SKILL.md from GitHub or SkillsMP and dropping it in your skills folder takes two minutes. Run it in a fresh session and observe the behavior before relying on it. A community skill you understand is more reliable than one you treat as a black box.

Last updated: 2026-05-03