How to Create Your First Claude Code Skill in 10 Minutes

Summary:

1. Correct directory: .claude/skills/ in your project (not root skills/).
2. Four-part anatomy: trigger, instructions, constraints, examples.
3. Before/after proof: unconfigured Claude vs. skill-configured Claude.
4. Three checks that fix 90% of loading failures.
5. Global vs. project-level skills.

Matt Maher’s video “Build a Claude Code Skill in 60 Seconds” hit 74K views because the concept is that simple. Drop a markdown file in a folder, restart Claude, and it follows your rules.

The part the video doesn’t cover: why your first skill sometimes doesn’t load, and what good skill anatomy looks like versus what breaks.

What is a Claude Code skill?

A SKILL.md file is a markdown document in .claude/skills/ that contains rules Claude follows for your project (the Claude Code documentation covers the full directory structure). Every time Claude starts a session, it reads these files and applies the instructions to everything it generates.

The critical detail: the directory is .claude/skills/ inside your project, not skills/ at the root. This trips up everyone on first try.

# Correct: Claude reads this automatically
mkdir -p .claude/skills/
touch .claude/skills/code-style.md

# Wrong: Claude ignores this completely
mkdir -p skills/
touch skills/code-style.md

For rules you want across every project (writing style, personal preferences), use the global directory: ~/.claude/skills/. Files there apply to all projects on your machine. (See the Claude Code docs for the full path resolution order.)

What goes inside a skill file?

Four parts: trigger, instructions, constraints, and examples. Every skill follows this structure.

# Code Style

## Trigger
When writing or modifying TypeScript files

## Instructions
- Use kebab-case for filenames: `user-profile.ts` not `userProfile.ts`
- Named exports only: `export function` not `export default`
- Import ordering: built-in → external → internal → types
- Type annotations on all function parameters and return values
- No `any` type. Use `unknown` and narrow with type guards

## Constraints
- Never use default exports
- Never use `var`. Only `const` and `let`
- Never leave type parameters as `any`

## Examples
Bad: export default function getData(id) { ... }
Good: export function getUserProfile(userId: string): Promise<UserProfile> { ... }

Trigger tells Claude when the skill activates. Instructions are the rules. Constraints are the hard “never do this” limits. Examples show correct output so Claude has a concrete reference.

How different is the output?

Night and day. Here’s what unconfigured Claude generates versus skill-configured Claude for the same prompt: “Create a function that fetches user data by ID.”

Before (no skill):

export default function fetchData(id) {
  var data: any = await fetch(`/api/users/${id}`);
  return data;
}

Default exports. var. any type. Generic variable names. No type annotations. This is what you get when Claude has no context about your preferences.

After (with code-style skill):

export async function fetchUserProfile(
  userId: string
): Promise<UserProfile> {
  const response = await fetch(`/api/users/${userId}`);
  if (!response.ok) {
    throw new ApiError(`Failed to fetch user ${userId}`, response.status);
  }
  const userProfile: UserProfile = await response.json();
  return userProfile;
}

Named export. const. Typed parameters and return value. Meaningful names. Error handling. Same prompt, completely different quality.

How do you verify it loaded?

The fastest test: ask Claude directly.

You: What coding style rules are you following?

A skill-aware Claude will say something like: “I’m following your code-style skill: kebab-case filenames, named exports only, import ordering built-in then external then internal then types, and type annotations on all function parameters.”

If Claude gives a generic answer about “best practices” or “clean code principles,” the skill didn’t load.

What are the three loading checks?

When your skill doesn’t load, it’s one of three things. Every time.

# Check 1: Is the file in the correct path?
ls -la .claude/skills/
# Must show your .md files here. Not in skills/ at root.

# Check 2: Does the file have the .md extension?
file .claude/skills/code-style*
# Watch for .md.txt (some editors add hidden extensions)
# macOS is especially guilty of this with TextEdit

# Check 3: Did you restart the session?
# Claude reads skills at session start.
# Adding a file mid-session does NOT activate it.
# Exit and re-enter Claude Code.

Real example that cost someone an hour of debugging: their skill file was saved as code-style.md.txt because their text editor appended a hidden .txt extension. The file showed up as code-style.md in Finder but Claude didn’t recognize it. Running file .claude/skills/code-style* revealed the true extension.

What broke

My first skill was 80 lines long. It covered code style, testing preferences, documentation rules, git commit format, and error handling patterns. Claude loaded it, but the output was inconsistent. Some rules fired, others got ignored.

The problem: too much in one file. Claude processes skills with limited context attention. An 80-line skill with 5 different concerns means each concern gets partial attention.

Fix: one concern per skill file. Split the 80-line monster into 5 files of 15-20 lines each. Every rule started firing consistently.

# Bad: one giant skill
.claude/skills/
  everything.md    # 80 lines, 5 concerns, inconsistent output

# Good: focused skills
.claude/skills/
  code-style.md       # 15 lines: file naming, exports, imports
  testing.md          # 18 lines: framework, assertions, edge cases
  documentation.md    # 12 lines: JSDoc rules
  git-commits.md      # 10 lines: conventional commits
  error-handling.md   # 14 lines: error patterns, logging

What should you actually do?

• Right now —> create .claude/skills/ in your project and add one skill file. Pick the thing you correct most often (naming, test framework, import style). Write 10-15 lines. Restart Claude. Test it.
• If it doesn’t load —> run the three checks: correct path, .md extension (not .md.txt), session restarted. This fixes 90% of loading issues.
• After your first skill works —> add a second one for a different concern. Keep each file under 20 lines and focused on one topic. You will see compounding results by skill three.

bottom_line

• A skill is a markdown file in .claude/skills/ with four parts: trigger, instructions, constraints, examples. Build your first one in 10 minutes.
• The three loading checks (path, extension, session restart) fix almost every “skill not working” issue. Run them before debugging anything else.
• One concern per skill file. An 80-line file with 5 topics produces inconsistent results. Five 15-line files produce reliable results.