Build your first skill

Step 1 — Decide what the skill does

Before any code, answer four questions in one sentence each:

• Trigger: When should Claude invoke this skill?
• Inputs: What does it need?
• Output: What does it produce?
• Tools: What permissions does it need?

If you can't answer all four in one sentence, the skill is doing too much. Split it.

Step 2 — Create the folder

mkdir -p ~/.claude/skills/commit-classifier/scripts
cd ~/.claude/skills/commit-classifier

Folder name = skill name = the name field in frontmatter. Lowercase kebab-case throughout.

Step 3 — Write SKILL.md

This is the entire skill. Frontmatter on top, instructions below.

---
name: commit-classifier
description: |
  Write a conventional-commit-style commit message from the currently staged
  diff. Triggers when the user asks Claude to "write a commit message",
  "what should I name this commit", or "/commit" after running git add.
  Inspects git diff --cached, classifies the change, and produces a tight,
  project-style message.
allowed-tools:
  - Bash
  - Read
version: 0.1.0
---

# commit-classifier

When this skill activates:

1. Run scripts/inspect.sh to gather staged diff, paths, last 10 commits.
2. Classify the change into: feat / fix / refactor / docs / test / chore / perf / style / build / ci.
3. Pick a scope from changed paths (deepest dir shared by >50% of files).
4. Write a subject line: imperative mood, <60 chars, no trailing period.
   Format: <type>(<scope>): <subject>
5. Print the message in a code block. Do NOT run git commit.

Step 4 — Add a helper script

Anything deterministic should live in a script — fewer tokens, more reliable, testable on its own.

# scripts/inspect.sh
#!/usr/bin/env bash
set -euo pipefail
echo "=== Staged paths ==="
git diff --cached --name-only
echo "=== Staged diff ==="
git diff --cached
echo "=== Recent commits ==="
git log -10 --pretty=format:"%s"

chmod +x scripts/inspect.sh

Step 5 — Test the trigger

Open a fresh Claude Code session in a repo with staged changes and try variations:

• "Write a commit message for what I just staged" → should activate
• "What should I name this commit?" → should activate
• "Help me think about my architecture" → should not activate

If it doesn't activate when expected, the description is too narrow. If it activates when it shouldn't, it's too broad.

Step 6 — Iterate on the description

80% of skill quality comes from the description. Tighten it in passes:

• Pass 1 — Trigger phrases. List exact phrases users say. Quote them.
• Pass 2 — Negative scope. If getting false positives, add "Does NOT apply to X" sentences.
• Pass 3 — Input shape. Mention attached files, staged state, current branch.

Step 7 — Package & publish

Share with teammates by committing the folder to a repo:

cd ~/.claude/skills/commit-classifier
git init
git add SKILL.md scripts/
git commit -m "Initial commit-classifier skill"
gh repo create my-team/claude-commit-classifier --public --source=. --push

Teammates install with:

git clone https://github.com/my-team/claude-commit-classifier \
  ~/.claude/skills/commit-classifier

For wider distribution, bundle it into a plugin.

Templates

Minimal SKILL.md

---
name: my-skill
description: One sentence saying when to use this skill and what it does.
---

# My Skill

When invoked, do X, then Y.

Skill with Bash + bundled script

---
name: my-skill
description: Trigger phrase, more phrase, action verb describing what it does.
allowed-tools:
  - Bash
  - Read
---

# My Skill

1. Run scripts/run.sh to gather inputs.
2. Decide based on output.
3. Report back to the user.

Skill with lookup table

---
name: api-error-helper
description: |
  When the user pastes an HTTP error response from our API or asks
  "what does error X mean", look up the code in reference/errors.md
  and walk through the documented remediation.
allowed-tools:
  - Read
---

# API Error Helper

1. Find the error code in reference/errors.md.
2. Quote the description and the listed remediation steps.
3. If the code is not listed, say so explicitly. Do not guess.

Pre-publish checklist

• [ ] name matches the folder name (kebab-case)
• [ ] description includes 2+ concrete trigger phrases
• [ ] allowed-tools is the minimum needed
• [ ] Scripts have an execute bit (chmod +x)
• [ ] Heavy reference content is in reference/*.md, not inlined
• [ ] Tested with three positive trigger phrases and two negatives
• [ ] Tested in a fresh session, not the one where you built it
• [ ] README explains what the skill does, install command, version
• [ ] LICENSE file (MIT, Apache-2.0, or BSL)