Project 9: Hello World Skill - Git Commit Assistant
Project 9: Hello World Skill - Git Commit Assistant
Build your first Claude Code skill that Claude auto-discovers and invokes when you mention commits.
Quick Reference
| Attribute | Value |
|---|---|
| Difficulty | Beginner |
| Time Estimate | 2-4 hours |
| Language | Markdown (SKILL.md) |
| Prerequisites | Basic git knowledge, understanding of Claude Code |
| Key Topics | Skills, skill discovery, prompt engineering, YAML frontmatter |
| Knowledge Area | Skills / Git / Developer Workflow |
| Main Book | “Pro Git” by Scott Chacon |
1. Learning Objectives
By completing this project, you will:
- Understand the SKILL.md format: Master the YAML frontmatter and markdown body structure that defines a skill
- Grasp skill discovery mechanics: Learn how Claude matches skill descriptions to user intent
- Write effective skill descriptions: Create descriptions that trigger appropriately without over-matching
- Implement single-purpose design: Scope a skill to do one thing well
- Test skill activation: Verify that Claude discovers and invokes your skill correctly
- Apply prompt engineering: Write clear instructions that guide Claude’s behavior
2. Theoretical Foundation
2.1 What Are Claude Code Skills?
Skills are the building blocks of Claude Code automation. They are declarative markdown files that define reusable capabilities Claude can invoke. Unlike slash commands (explicit user invocation), skills are implicitly discovered when Claude detects a matching description in the user’s request.
┌─────────────────────────────────────────────────────────────────────────┐
│ SKILL vs SLASH COMMAND │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ SKILL (Implicit Discovery) SLASH COMMAND (Explicit Invocation)│
│ ────────────────────────── ──────────────────────────────────│
│ │
│ User: "I want to commit my changes" User: "/commit" │
│ │ │ │
│ ▼ ▼ │
│ Claude: "Hmm, this matches the Claude: "User explicitly called │
│ git-commit skill description" the commit command" │
│ │ │ │
│ ▼ ▼ │
│ [Invokes skill automatically] [Invokes command directly] │
│ │
│ Key: Natural language triggers Key: Explicit command triggers │
│ │
└─────────────────────────────────────────────────────────────────────────┘
2.2 The SKILL.md File Format
Every skill is defined in a SKILL.md file with two parts:
---
# YAML Frontmatter - Metadata
name: skill-name
description: What this skill does and when to use it
allowed-tools: # Optional: restrict available tools
- Bash
- Read
---
# Markdown Body - Instructions
When the user wants to [do something], follow these steps...
YAML Frontmatter Fields:
| Field | Required | Purpose |
|---|---|---|
name |
Yes | Unique identifier for the skill |
description |
Yes | Critical: This is what Claude matches against user intent |
allowed-tools |
No | Restrict which tools Claude can use (security/focus) |
2.3 Skill Discovery: How Claude Finds Skills
Claude’s skill discovery works through semantic matching:
┌─────────────────────────────────────────────────────────────────────────┐
│ SKILL DISCOVERY FLOW │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ User Message: "I'm ready to commit my changes" │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────┐ │
│ │ Claude analyzes the message │ │
│ │ looking for intent signals │ │
│ └─────────────────┬───────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────┐ │
│ │ Compare against all skill descriptions│ │
│ │ │ │
│ │ git-commit: "Help create well- │ ◄─── MATCH! (commit, │
│ │ formatted git commit messages..." │ changes, git) │
│ │ │ │
│ │ web-testing: "Automate web browser │ ◄─── No match │
│ │ testing including login flows..." │ │
│ │ │ │
│ │ doc-generator: "Generate documentation│ ◄─── No match │
│ │ for code modules..." │ │
│ └─────────────────┬───────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────┐ │
│ │ Best match: git-commit skill │ │
│ │ → Load and follow its instructions │ │
│ └─────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
Key insight: The description field is the most important part of your skill. It determines when Claude will choose to use it.
2.4 Skill Locations
Skills can be stored in two locations:
| Location | Scope | Path |
|---|---|---|
| User-level | Available in all projects | ~/.claude/skills/skill-name/SKILL.md |
| Project-level | Available in specific project | .claude/skills/skill-name/SKILL.md |
Project-level skills take precedence over user-level skills with the same name.
2.5 Progressive Disclosure
Skills support progressive disclosure—loading additional files only when needed:
skill-name/
├── SKILL.md # Always loaded when skill is invoked
├── REFERENCES.md # Loaded on-demand when referenced
├── templates/ # Loaded on-demand
│ └── format.md
└── scripts/ # Executed when called
└── helper.py
This keeps context small while maintaining access to rich resources.
2.6 Conventional Commits
This project teaches you to implement the Conventional Commits specification:
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
Types:
| Type | When to Use |
|——|————-|
| feat | New feature for the user |
| fix | Bug fix for the user |
| docs | Documentation only changes |
| style | Formatting, no code change |
| refactor | Refactoring production code |
| test | Adding or refactoring tests |
| chore | Updating build tasks, configs, etc. |
Examples:
feat(auth): add login with OAuth2 support
fix(api): handle null response from payment gateway
docs: update API documentation for v2 endpoints
refactor(database): extract connection pooling logic
3. Project Specification
3.1 What You Will Build
A Claude Code skill that:
- Auto-discovers when users mention commits or staging changes
- Analyzes the current git state (staged, unstaged, untracked files)
- Suggests a well-formatted conventional commit message
- Confirms with the user before committing
3.2 Functional Requirements
- Skill Discovery: The skill should activate when users say things like:
- “I want to commit my changes”
- “commit this”
- “ready to commit”
- “help me create a commit message”
- Git State Analysis: When invoked, the skill should:
- Check staged changes (
git status) - Show what files are affected
- Analyze the nature of changes (
git diff)
- Check staged changes (
- Commit Message Generation: The skill should:
- Suggest appropriate commit type (feat, fix, docs, etc.)
- Identify scope from file paths if possible
- Write a concise description
- Include bullet points for body if multiple changes
- User Confirmation: Always confirm before committing
3.3 Non-Functional Requirements
- Precision: Don’t trigger on unrelated git commands (push, pull, branch)
- Helpful: Explain why a particular commit type was chosen
- Safe: Never commit without user confirmation
- Educational: Teach users about conventional commits
4. Real World Outcome
When you complete this project, here’s exactly what you’ll experience:
You: I'm ready to commit my changes
Claude: [Auto-discovers and invokes git-commit skill]
I'll help you create a well-formatted commit. Let me check your changes...
Staged Changes:
- src/auth/login.ts (modified)
- src/auth/logout.ts (new file)
- tests/auth.test.ts (modified)
Analyzing changes...
The changes appear to:
- Add a new logout function (new file)
- Update login to work with the new logout flow
- Add test coverage for logout
Based on these changes, here's a suggested commit message:
feat(auth): add logout functionality and update login flow
- Implement logout endpoint with token invalidation
- Update login to support remember-me option
- Add tests for new logout functionality
Commit Type: `feat` (new feature - the logout functionality is new)
Scope: `auth` (all changes are in the auth module)
Shall I proceed with this commit message, or would you like to modify it?
5. The Core Question You’re Answering
“How do I create reusable capabilities that Claude automatically discovers and invokes based on user intent?”
This project answers that question by teaching you:
- The mechanics of skill discovery
- How to write descriptions that match intent
- How to structure instructions Claude follows
- The difference between skills (implicit) and commands (explicit)
6. Concepts You Must Understand First
Stop and research these before coding:
6.1 SKILL.md Structure
| Concept | Questions to Answer | Reference |
|---|---|---|
| YAML frontmatter | What fields are required? What are optional? | Claude Code Docs - “Skills” |
| Markdown body | What should go here? How detailed? | Claude Code Docs - “Skills” |
| Skill location | Where do skills live? User vs project level? | Claude Code Docs - “Skills” |
6.2 Skill Discovery
| Concept | Questions to Answer | Reference |
|---|---|---|
| Description matching | How does Claude decide to use a skill? | Claude Code Docs - “Skill Discovery” |
| Keyword importance | What words should be in the description? | Experiment with your skill |
| Avoiding over-matching | How do you prevent false positives? | Single-purpose design principle |
6.3 Git Operations
| Concept | Questions to Answer | Reference |
|---|---|---|
| Git status | What does git status tell you? |
“Pro Git” Ch. 2 |
| Git diff | How do you see what changed? | “Pro Git” Ch. 2 |
| Conventional commits | What are the types and when to use them? | conventionalcommits.org |
7. Questions to Guide Your Design
Before implementing, think through these:
7.1 Skill Scope
- Should this skill ONLY handle commits?
- Or should it cover all git operations (push, pull, branch)?
- What’s the right granularity?
Recommended: Single-purpose. A commit skill that does commits well is better than a git skill that does everything poorly.
7.2 Discovery Keywords
- What phrases should trigger this skill?
- “commit”, “commit my changes”, “create a commit”
- How specific should the description be?
Recommended: Include multiple variations: “commit”, “commit message”, “git commit”, “stage and commit”
7.3 Instructions Content
- What should Claude do when this skill is invoked?
- Check staged changes?
- Suggest conventional commit format?
- Auto-stage related files?
Recommended: Always check status first, analyze changes, then suggest—never auto-commit without confirmation.
8. Thinking Exercise
8.1 Design the SKILL.md
Before writing, sketch out the structure:
---
name: git-commit
description: ??? # What triggers discovery?
allowed-tools: # Should you restrict tools?
- Bash
- Read
---
# Instructions
When the user wants to commit changes...
## What to do:
1. ???
2. ???
3. ???
## Commit message format:
???
Questions to answer:
- What description will match “I want to commit my changes”?
- Should you include “git” in the description?
- What tools does Claude need for this skill?
8.2 Trace Through Discovery
Imagine these user messages. Which should trigger your skill?
| User Message | Should Trigger? | Why/Why Not? |
|---|---|---|
| “I want to commit my changes” | Yes | Direct intent |
| “commit this” | Yes | Clear intent |
| “push my changes to GitHub” | No | Different operation |
| “what did I change?” | Maybe | Could be checking before commit |
| “create a PR” | No | Different workflow |
Adjust your description to match only the appropriate cases.
9. The Interview Questions They’ll Ask
After completing this project, you’ll be ready for:
- “How would you create a reusable capability for an AI coding assistant?”
- Expected: Explain skills as declarative capabilities with descriptions for discovery
- Bonus: Discuss trade-offs between skills (implicit) and commands (explicit)
- “What’s the difference between explicit and implicit invocation?”
- Expected: Slash commands are explicit; skills are discovered from intent
- Bonus: When to use each approach
- “How do you scope a skill to avoid over-matching?”
- Expected: Specific descriptions, single-purpose design, testing
- Bonus: Discuss precision vs recall in skill matching
- “How would you test that a skill is discovered correctly?”
- Expected: Try various phrasings, check for false positives/negatives
- Bonus: Create a test matrix of inputs and expected behaviors
- “What are the security implications of skill auto-discovery?”
- Expected: Skills can restrict tools, but users should understand what’s activated
- Bonus: Discuss
allowed-toolsfor limiting capabilities
10. Solution Architecture
10.1 Skill Directory Structure
~/.claude/skills/git-commit/
└── SKILL.md # Your skill definition
10.2 SKILL.md Components
┌─────────────────────────────────────────────────────────────────────────┐
│ SKILL.md STRUCTURE │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────┐ │
│ │ YAML FRONTMATTER │ │
│ │ ───────────────────────────────────── │ │
│ │ name: git-commit │ ◄─── Unique identifier │
│ │ description: Help create well- │ ◄─── Discovery trigger │
│ │ formatted git commit messages... │ │
│ └─────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────┐ │
│ │ MARKDOWN BODY │ │
│ │ ───────────────────────────────────── │ │
│ │ │ │
│ │ # Git Commit Assistant │ ◄─── Title │
│ │ │ │
│ │ ## 1. Check Current State │ ◄─── Step-by-step │
│ │ Run `git status`... │ instructions │
│ │ │ │
│ │ ## 2. Analyze Changes │ │
│ │ For each changed file... │ │
│ │ │ │
│ │ ## 3. Suggest Commit Message │ │
│ │ Follow conventional commit format... │ │
│ │ │ │
│ │ ## 4. Confirm with User │ │
│ │ Present suggestion and wait... │ │
│ │ │ │
│ └─────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
10.3 Workflow Diagram
┌─────────────────────────────────────────────────────────────────────────┐
│ GIT COMMIT SKILL WORKFLOW │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ User: "I want to commit my changes" │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Skill Discovery │ Match against "commit", "commit message", etc. │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ 1. Git Status │ Run: git status │
│ │ Check state │ Identify: staged, unstaged, untracked │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ 2. Analyze Diff │ Run: git diff --staged │
│ │ Understand │ Determine: what changed, what was added │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ 3. Determine │ Based on changes: │
│ │ Commit Type │ - New file? → feat │
│ │ │ - Bug fix? → fix │
│ │ │ - Docs only? → docs │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ 4. Suggest │ Format: type(scope): description │
│ │ Message │ Include body if multiple changes │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ 5. Confirm │ "Shall I proceed with this commit message?" │
│ │ with User │ Wait for explicit approval │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ 6. Execute │ Run: git commit -m "message" │
│ │ (if approved)│ Report success/failure │
│ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
11. Implementation Guide
11.1 Phase 1: Create the Skill Directory
# Create the skill directory
mkdir -p ~/.claude/skills/git-commit
# Create the SKILL.md file
touch ~/.claude/skills/git-commit/SKILL.md
11.2 Phase 2: Write the Frontmatter
---
name: git-commit
description: Help create well-formatted git commit messages following conventional commit format. Use this when the user mentions committing, staging, or preparing changes for git.
---
Why this description works:
- “commit messages” - matches “I want to commit”
- “conventional commit format” - signals this is about formatting
- “committing, staging, or preparing changes” - covers related intents
11.3 Phase 3: Write the Instructions
# Git Commit Assistant
When the user wants to create a commit, follow these steps:
## 1. Check Current State
Run `git status` to see:
- What files are staged
- What files are modified but not staged
- What files are untracked
## 2. Analyze Changes
For each changed file, briefly understand what changed using `git diff --staged`.
If nothing is staged, suggest what should be staged.
## 3. Determine Commit Type
Based on the changes, select the appropriate type:
- `feat:` - A new feature
- `fix:` - A bug fix
- `docs:` - Documentation only changes
- `style:` - Formatting, missing semi colons, etc.
- `refactor:` - Code change that neither fixes a bug nor adds a feature
- `test:` - Adding or correcting tests
- `chore:` - Changes to build process or auxiliary tools
## 4. Identify Scope (Optional)
Look at file paths to determine scope:
- `src/auth/*` → scope: auth
- `src/api/*` → scope: api
- Multiple directories → omit scope or use most significant
## 5. Suggest Commit Message
Format: `type(scope): brief description`
If there are multiple significant changes, include a body:
type(scope): brief description
- Detail about first change
- Detail about second change ```
6. Confirm with User
Present the suggested message and ask: “Shall I proceed with this commit message, or would you like to modify it?”
Never commit without explicit user approval.
### 11.4 Phase 4: Test the Skill
Test with various phrasings:
| Test Input | Expected Behavior |
|------------|-------------------|
| "I want to commit my changes" | Skill activates, checks status |
| "commit this" | Skill activates |
| "help me write a commit message" | Skill activates |
| "push to origin" | Skill should NOT activate |
| "create a new branch" | Skill should NOT activate |
---
## 12. Hints in Layers
If you're stuck, reveal hints one at a time:
<details markdown="1">
<summary><strong>Hint 1: Create the Directory</strong></summary>
Create `~/.claude/skills/git-commit/SKILL.md` (user-level) or `.claude/skills/git-commit/SKILL.md` (project-level).
The directory name should match the skill name for clarity.
</details>
<details markdown="1">
<summary><strong>Hint 2: Write the Frontmatter</strong></summary>
```yaml
---
name: git-commit
description: Help create well-formatted git commit messages following conventional commit format
---
Include keywords users might say: “commit”, “commit message”, “stage”, “changes”. </details>
Hint 3: Add Instructions
Tell Claude to:
- Check
git statusfirst - Analyze changes with
git diff --staged - Suggest a commit message following conventional commits
- Always confirm before committing
Be specific about the format you want.
Hint 4: Test Discovery
Ask Claude “I want to commit my changes” and see if it mentions using the skill.
If it doesn’t activate:
- Check that the skill file is in the right location
- Verify the YAML frontmatter is valid
- Try more explicit triggers in your description
13. Common Pitfalls & Debugging
13.1 Frequent Mistakes
| Pitfall | Symptom | Solution |
|---|---|---|
| Skill not discovered | Claude doesn’t mention using the skill | Check description keywords, file location |
| YAML syntax error | Skill fails to load | Validate YAML, check indentation |
| Over-matching | Skill triggers on unrelated requests | Make description more specific |
| Under-matching | Skill doesn’t trigger when expected | Add more keyword variations |
| Committing without approval | Unsafe behavior | Add explicit confirmation step in instructions |
13.2 Debugging Steps
- Verify file location:
ls ~/.claude/skills/git-commit/SKILL.md - Check YAML validity: Use an online YAML validator
- Test explicitly: Ask Claude “Use the git-commit skill”
- Review Claude’s response: Does it mention loading the skill?
14. Extensions & Challenges
14.1 Beginner Extensions
- Add emoji to commit types (e.g.,
featgets sparkles) - Support for
--amendcommits - Show unstaged files and offer to stage them
14.2 Intermediate Extensions
- Add a REFERENCES.md with full conventional commit spec
- Support breaking change notation (
feat!:orBREAKING CHANGE:) - Integrate with git hooks for commit message validation
14.3 Advanced Extensions
- Multi-language commit message templates
- AI-powered commit message improvement suggestions
- Integration with issue trackers (add
Closes #123)
15. Books That Will Help
| Topic | Book | Chapter |
|---|---|---|
| Git workflows | “Pro Git” by Scott Chacon | Chapter 5: Distributed Workflows |
| Conventional commits | conventionalcommits.org | Full Specification |
| Prompt engineering | “Prompt Engineering Guide” | All sections |
| Git internals | “Pro Git” by Scott Chacon | Chapter 10: Git Internals |
16. Self-Assessment Checklist
Before considering this project complete, verify:
Understanding
- I can explain what a SKILL.md file contains
- I understand how skill discovery works (description matching)
- I know the difference between skills and slash commands
- I can explain conventional commit format
Implementation
- My skill activates when I mention committing
- My skill does NOT activate for unrelated git commands
- Claude follows my instructions (check status, analyze, suggest)
- Claude always confirms before committing
Growth
- I tested with at least 5 different phrasings
- I can create a new skill from scratch
- I understand when to use skills vs slash commands
17. Learning Milestones
Track your progress:
| Milestone | Indicator |
|---|---|
| Skill is discovered when you mention commits | You understand discovery |
| Claude follows your instructions | You understand skill instructions |
| Commits are well-formatted | You’ve created a useful skill |
| No false positives on unrelated commands | You’ve scoped correctly |
18. Submission / Completion Criteria
Minimum Viable Completion:
- SKILL.md file exists in correct location
- Skill activates on “I want to commit”
- Claude checks git status
Full Completion:
- Skill activates on multiple phrasings
- Claude suggests conventional commit format
- Claude explains commit type choice
- Claude confirms before committing
Excellence:
- Skill handles edge cases (nothing staged, untracked files)
- Includes scope detection from file paths
- Documentation explains design decisions
This guide was expanded from CLAUDE_CODE_MASTERY_40_PROJECTS.md. For the complete learning path, see the project index.