Skill Creator - How to Properly Create Claude Code Skills

Purpose

This skill teaches you how to create new Claude Code skills and where to put them. Use this EVERY TIME you need to create a new skill to avoid common mistakes.

Critical Rule: Global vs Project-Local

DEFAULT: GLOBAL SKILLS (

~/.claude/skills/

)

99% of skills belong here. This is your personal skills library that works across ALL projects.

Examples of global skills:

• housekeeping

  - Repository cleanup (works on any repo)

• update-readme

  - Documentation updates (works on any repo)

• handbook

  - Amplify Gen 2 knowledge (works across projects)

• skills-sync

  - Skill management (global utility)

Location:

~/.claude/skills/skill-name/SKILL.md

RARE: PROJECT-LOCAL SKILLS (

.claude/skills/

)

Only use this for skills that are specific to ONE project and make no sense elsewhere.

Example of a valid project-local skill:

• documentation-updater

  - Updates docs using THIS project's specific structure

Location:

.claude/skills/skill-name.md

When in Doubt: USE GLOBAL!

If you're asking "Should this be global or local?" → It's global.

How to Create a New Skill (Step-by-Step)

Step 1: Decide the Skill Name

Use lowercase-with-hyphens:

• ✅

  housekeeping

• ✅

  update-readme

• ✅

  code-review

• ❌

  Housekeeping

  (no capital letters)
• ❌

  update_readme

  (use hyphens, not underscores)

Step 2: Create the Directory

# For GLOBAL skills (default):
mkdir -p ~/.claude/skills/skill-name

# For PROJECT-LOCAL skills (rare):
mkdir -p .claude/skills/

Step 3: Create the SKILL.md File

# For GLOBAL skills:
# Use the Write tool to create:
# /Users/feather/.claude/skills/skill-name/SKILL.md

# For PROJECT-LOCAL skills:
# Use the Write tool to create:
# .claude/skills/skill-name.md

Step 4: Write the Skill Content

🚨 CRITICAL: Every SKILL.md MUST start with YAML frontmatter!

---
name: skill-name
description: Brief description of what this skill does and when to use it (max 1024 chars)
---

# Skill Name - Brief Description

## Purpose
What does this skill do? When should it be used?

## Activation
How do users invoke this skill?

Example:
"Hey Claude, use your skill-name skill to..."

## Workflow Overview
Step-by-step process of what the skill does.

## Critical Rules
Important things to remember.

## Success Criteria
How to know the skill completed successfully.

## Example
Show a real example of the skill in action.

YAML Frontmatter Requirements:

• name

  : Must match directory name, lowercase-with-hyphens (max 64 chars)

• description

  : What the skill does AND when to use it (max 1024 chars)
  • Include key trigger words users would mention
  • Be specific about when Claude should activate it
  • Example: "Extract text from PDFs, fill forms. Use when working with PDF files or when user mentions documents, forms, or PDFs."

Without YAML frontmatter, Claude cannot discover or use your skill!

Step 5: Commit to ChillSkills (GLOBAL ONLY)

cd ~/.claude/skills
git add skill-name/
git commit -m "feat: Add skill-name skill for [purpose]"
git pull --rebase origin main
git push origin main

DO NOT commit project-local skills to ChillSkills!

Common Mistakes to Avoid

❌ Mistake #1: Creating in Project-Local by Default

# WRONG:
vim .claude/skills/new-skill.md

# RIGHT:
mkdir -p ~/.claude/skills/new-skill
vim ~/.claude/skills/new-skill/SKILL.md

❌ Mistake #2: Wrong File Name

# WRONG:
~/.claude/skills/housekeeping/housekeeping.md

# RIGHT:
~/.claude/skills/housekeeping/SKILL.md

❌ Mistake #3: Using Underscores

# WRONG:
~/.claude/skills/update_readme/

# RIGHT:
~/.claude/skills/update-readme/

❌ Mistake #4: Missing YAML Frontmatter

CRITICAL ERROR - Skill won't work without it!

# WRONG - No frontmatter:
# My Skill

## Purpose
...

# RIGHT - Has frontmatter:
---
name: my-skill
description: Does X when you need Y
---

# My Skill

## Purpose
...

❌ Mistake #5: Forgetting to Push

After creating a global skill, ALWAYS push to ChillSkills:

cd ~/.claude/skills
git add new-skill/
git commit -m "feat: Add new-skill"
git push origin main

Quick Reference: File Structure

Global Skills Structure

~/.claude/skills/
├── .git/                           ← Git repo (ChillSkills)
├── skill-name/
│   └── SKILL.md                    ← The actual skill
├── another-skill/
│   └── SKILL.md
└── README.md

Project-Local Skills Structure (Rare)

.claude/skills/
├── project-specific-skill.md       ← Note: .md not SKILL.md
└── another-local-skill.md

Workflow: Creating a New Skill

Example: Creating "code-review" Skill

# Step 1: Create directory
mkdir -p ~/.claude/skills/code-review

# Step 2: Use Write tool to create SKILL.md with YAML frontmatter
# Write to: /Users/feather/.claude/skills/code-review/SKILL.md

---
name: code-review
description: Review code for best practices, security issues, and potential bugs. Use when reviewing code, checking pull requests, or analyzing code quality.
---

# Code Review Skill

## Purpose
Automated code review for quality, security, and best practices.

[Rest of skill content...]

# Step 3: Commit to ChillSkills
cd ~/.claude/skills
git add code-review/
git commit -m "feat: Add code-review skill for automated code reviews"
git pull --rebase origin main
git push origin main

# Done! ✅

Testing Your New Skill

After creating the skill:

1. Restart Claude Code (or wait a moment for auto-reload)
2. Invoke the skill:

   User: "Use your skill-name skill to..."
   

3. Verify it works as expected

Updating Existing Skills

To Update a Global Skill:

# Edit the file
vim ~/.claude/skills/skill-name/SKILL.md

# Commit changes
cd ~/.claude/skills
git add skill-name/SKILL.md
git commit -m "fix: Update skill-name with improved workflow"
git push origin main

To Update a Project-Local Skill:

# Edit the file
vim .claude/skills/skill-name.md

# Commit to project repo
git add .claude/skills/skill-name.md
git commit -m "chore: Update skill-name skill"

Decision Tree: Global vs Project-Local

Ask yourself:

Q1: Does this skill work on ANY repository?

• Yes → GLOBAL
• No → Continue to Q2

Q2: Is this skill specific to THIS project's unique structure/workflow?

• Yes → PROJECT-LOCAL
• No → GLOBAL (if in doubt, always global!)

Examples:

• "Housekeeping" works on any repo → GLOBAL
• "Update README" works on any repo → GLOBAL
• "Deploy to AWS" works on any Amplify project → GLOBAL
• "Update BEONIQ-specific docs" only works here → PROJECT-LOCAL

Success Criteria

When creating a skill, you should:

✅ YAML frontmatter with

name

description

~/.claude/skills/skill-name/SKILL.md

SKILL.md

skill-name.md

Remember

Default location:

~/.claude/skills/skill-name/SKILL.md

When in doubt: Use global, not project-local!

Always push: Commit global skills to ChillSkills repo!

ChillSkills Repository

Global skills are version-controlled at:

https://github.com/ChinchillaEnterprises/ChillSkills

This ensures:

• Skills are shared across machines
• Version history is preserved
• Collaborative skill development
• Easy rollback if something breaks

Quick Checklist for Creating a Skill

Before you create a skill, verify:

• 🚨 YAML frontmatter with

  name

  and

  description

  at the top
• Skill name is lowercase-with-hyphens
• Creating in

  ~/.claude/skills/skill-name/

  (not

  .claude/skills/

  )
• File is named

  SKILL.md

  (not

  skill-name.md

  )
• Description includes trigger words and when to use it
• Skill has Purpose, Activation, Workflow, and Success Criteria
• Committed and pushed to ChillSkills (if global)
• Tested that skill works after creation

Every time you create a skill, follow this guide!