How to Create and Utilize Skills in Claude Code: A Complete Guide

Claude Code uses a progressive-disclosure architecture that loads only skill metadata at startup, instructions when matched, and resources on-demand, allowing you to create reusable expertise packages that auto-invoke or respond to manual /skill-name commands.

The luongnv89/claude-howto repository demonstrates how to extend Claude Code with custom skills following the Anthropic Agent Skills open standard. This guide explains how to create and utilize skills in Claude Code based on the reference implementation and bundled examples found in the source code.

Understanding the Progressive-Disclosure Architecture

Claude Code implements a three-tier loading system that minimizes context window usage while maximizing available capabilities. According to 03-skills/README.md, this architecture ensures you can install dozens of skills without degrading performance.

Level 1: Metadata (Front-Matter)

At startup, Claude scans only the metadata from each skill's YAML front-matter—specifically the name and description fields. This consumes approximately 100 tokens per skill and allows Claude to match requests against capability descriptions without loading full instruction sets.

Level 2: Instructions (SKILL.md Body)

When a request matches a skill's description, Claude loads the instructions from that skill's SKILL.md file. The instructional body contains the actual workflow logic and is capped at roughly 5,000 tokens. This SKILL.md file resides in the skill's root directory and combines the front-matter with detailed operational guidance.

Level 3: Resources (On-Demand Files)

Additional supporting materials—templates, scripts, reference documentation, or example files—remain unloaded until explicitly referenced. These resources incur zero context cost until the skill's instructions call for them, making it efficient to include comprehensive supporting assets.

Step-by-Step: How to Create a Skill in Claude Code

Creating a skill requires a specific directory structure and a properly formatted SKILL.md file. Follow these steps based on the implementation in luongnv89/claude-howto:

1. Choose a location – Use ~/.claude/skills/ for personal (global) availability or .claude/skills/ for project-specific skills.
2. Create a directory – Name it after your skill (e.g., my-skill/).
3. Add SKILL.md – Include required front-matter fields (name, description) plus instructional content.
4. Add supporting files – Optionally include scripts, templates, or docs in the same directory.
5. Install – Copy the directory into your chosen skills location.
6. Invoke – Use automatic matching or manual /skill-name syntax.

Here is a complete example for creating a custom skill:

# Create the skill directory (personal location)

mkdir -p ~/.claude/skills/my-skill
cd ~/.claude/skills/my-skill

# Create the required SKILL.md with front-matter

cat > SKILL.md <<'EOF'
---
name: my-skill
description: Perform a custom transformation on a source file. Use when the user asks to transform a source file.
---

# My Skill

## Instructions

1. Read the file path passed as the first argument.
2. Apply the transformation logic (e.g., replace tabs with four spaces).
3. Output the transformed content.

## Example Invocation

```bash
/my-skill src/main.py

EOF

mkdir scripts cat > scripts/transform.py <<'EOF' #!/usr/bin/env python3 import sys, re path = sys.argv[1] with open(path) as f: data = f.read() print(re.sub(r'\t', ' ', data)) EOF chmod +x scripts/transform.py

## Installing and Invoking Skills

Once created, skills must be properly installed and can be triggered through two distinct mechanisms.

### Automatic Invocation

Claude automatically invokes a skill when your request semantically matches its `description` field. For example, stating "review this code for security" triggers the **code-review** skill because its description contains relevant keywords. This matching happens against the Level 1 metadata without requiring you to remember specific command names.

### Manual Invocation

You can explicitly call any skill using the forward-slash syntax followed by the skill name defined in the front-matter:

```bash

# Invoke the bundled code-review skill

/code-review src/auth/login.ts

# Invoke your custom skill

/my-skill src/main.py

As shown in README.md lines 150-164, installation simply requires copying the skill directory to the appropriate location:

# Install the code-review skill from the repository

cp -r 03-skills/code-review ~/.claude/skills/

# Or for project-specific use

cp -r 03-skills/code-review ./.claude/skills/

Real-World Examples from the Repository

The luongnv89/claude-howto repository includes production-ready skills that demonstrate best practices for structure and documentation.

Code Review Skill

Located at 03-skills/code-review/SKILL.md, this skill showcases detailed instructions for automated code analysis. It includes specific guidance for security checks, performance optimization, and style consistency, serving as a template for skills requiring complex multi-step workflows.

API Documentation Generator

The 03-skills/doc-generator/SKILL.md file illustrates how to create skills that generate structured output. It demonstrates complex formatting requirements and resource utilization patterns for documentation tasks.

Both files provide concrete templates for your own SKILL.md structure, showing exactly how to balance the front-matter metadata with actionable instruction content.

Summary

• Progressive disclosure loads only ≈100 tokens of metadata per skill at startup, expanding to full instructions (≤5k tokens) only when matched, and fetching additional resources on-demand.
• Skill creation requires a directory containing a SKILL.md file with name and description front-matter fields, placed in either ~/.claude/skills/ (personal) or .claude/skills/ (project).
• Installation involves copying the skill directory to the appropriate location; no build step or registry submission is required.
• Invocation occurs automatically via description matching or manually through the /skill-name command syntax.
• Reference implementations in 03-skills/code-review/SKILL.md and 03-skills/doc-generator/SKILL.md provide working templates for custom development.

Frequently Asked Questions

What is the maximum size for a skill's instructions?

According to the architecture defined in 03-skills/README.md, the instructional body within SKILL.md should not exceed approximately 5,000 tokens. This limit ensures that loading Level 2 content maintains system responsiveness while still allowing for detailed workflow descriptions.

Can I share skills between projects or team members?

Yes. Skills placed in ~/.claude/skills/ are available globally to all Claude Code sessions on your machine, while .claude/skills/ directory skills are project-specific. You can version control the .claude/skills/ directory within a repository to share standardized capabilities across a development team.

How does Claude choose which skill to invoke automatically?

Claude compares your request against the description field in each skill's YAML front-matter (Level 1 metadata). If your request semantically matches the description—such as asking to "review code" matching a skill described as "performing code reviews"—Claude loads that skill's instructions and executes its workflow.

What file types can I include as Level 3 resources?

You can include any file type as supporting resources: Python scripts, Bash scripts, Markdown templates, JSON schemas, or reference documentation. These files remain unloaded until the skill's instructions explicitly reference them, so including large assets does not impact the initial context window.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}