Build Your AI Superpowers from Scratch: A Hands‑On Guide to Creating Claude Code Skills

1. What Is a Skill?

A skill is a standardized workflow that tells Claude Code how to perform a specific task, turning a smart AI assistant into a repeatable “employee” that can execute the same steps without re‑explaining each time.

Four Types of Skills

Built‑in skills – preinstalled, ready to use (e.g., verify, debug).

Project skills – stored in .claude/skills/ inside a project and usable only for that project.

User skills – stored in ~/.claude/skills/ and available across all projects on the machine.

Plugin skills – added via external plugins.

2. How Claude Code Uses Skills

Skill execution workflow

User issues a command, e.g., /code-review my-file.ts.

Claude Code scans the skill directories, finds the matching skill file (e.g., code-review), and loads its definition.

The assistant follows the steps defined in the skill – reading files, analyzing code, generating a report.

The result (problem list, improvement suggestions, etc.) is returned to the user.

Two invocation methods

Explicit call : the user types the skill name directly, suitable when the desired action is known.

Natural‑language call : the user describes the need (e.g., "Help me review this code"), and Claude Code selects the appropriate skill automatically.

Skill lifecycle

Loading – Claude Code scans all skill folders at startup.

Registration – validates each skill file and adds it to the available list.

Ready – the skill waits to be invoked.

Invocation – user command or description triggers skill matching.

Execution – the assistant runs the commands defined in the skill, possibly calling other tools.

Completion – results are shown and temporary resources are cleaned up.

3. Skill File Format

File structure

.claude/
└── skills/
    └── my-first-skill/
        └── SKILL.md

Metadata (required)

name

– lower‑case, hyphenated identifier (e.g., code-review). description – one‑sentence summary of what the skill does.

Optional metadata fields

whenToUse

– conditions for invoking the skill. aliases – alternative names. allowedTools – list of tools the skill may call. argumentHint – placeholder for required arguments (e.g., "[file path]").

Content section

Written in Markdown, it describes the exact steps the assistant should perform.

# Skill Title

## Overview
Brief description of the skill’s purpose.

## Usage Steps
1. First step
2. Second step
3. Third step

## Notes
Caveats or special considerations.

## Example
Concrete command usage.

4. Creating Your First Skill

Preparation (3 minutes)

Answer three questions:

What problem are you solving? (e.g., automatically generate a project README).

What steps are required? (e.g., read package.json, analyze structure, generate content).

What input does the user need to provide? (e.g., project path).

Six creation steps

Create the folder – either project‑level ( .claude/skills/readme-generator/) or user‑level ( ~/.claude/skills/readme-generator/).

Add SKILL.md – the file name must be capitalised.

Write metadata – copy the template with name, description, whenToUse, argumentHint, etc.

Write the content – include overview, usage steps, notes, and an example.

Save the file .

Test immediately – restart Claude Code and run either /readme-generator ./my-project or the natural‑language prompt "Help me generate a README for this project".

5. Skill Development Best Practices

Design principles

One skill, one purpose – e.g., code-review only reviews code; avoid multi‑purpose “super‑tools”.

Start simple, then grow – provide a minimal three‑step usage, then add advanced options.

Provide clear examples – concrete command snippets make the skill easier to adopt.

Writing tips

Use numbered steps for clarity.

Prefer simple language over verbose technical jargon.

Include a checklist to ensure all required actions are performed.

Testing your skill

Basic functionality – call the skill with minimal arguments and verify expected output.

Boundary cases – test empty, invalid, or special‑character arguments.

User‑experience – have someone unfamiliar try the skill and note difficulties.

Maintenance

Perform a monthly review to confirm relevance and update steps.

Collect user feedback on problems, suggestions, and new feature requests.

Use a version field in metadata to track changes.

6. Summary

A skill is a reusable, standardized AI workflow that boosts efficiency, guarantees quality, supports team collaboration, and can be continuously refined. Building one involves six straightforward steps: create the folder, add SKILL.md, write metadata, define the execution steps, save, and test. Follow the design principles, write clear documentation, test thoroughly, and maintain the skill over time to get the most out of Claude Code.