# Create Skill

> Guide for creating well-structured Claude Code skills following best practices.

- Skill: `waterhyacinthinnanhu/create-skill` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add waterhyacinthinnanhu/create-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/waterhyacinthinnanhu/create-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: WaterHyacinthInNANHU (https://skillmd.com/u/waterhyacinthinnanhu)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/waterhyacinthinnanhu/create-skill

---


# create_skill

Guide for creating well-structured Claude Code skills following best practices.

## Skill Structure

A skill should be organized as a directory with multiple files:

```
skills/
└── skill_name/
    ├── SKILL.md        # Main documentation (required)
    ├── examples.md     # Usage examples
    ├── reference.md    # Quick reference / cheatsheet
    └── templates/      # Reusable templates
        └── *.sh, *.py, etc.
```

## SKILL.md Structure

The main skill file **must** start with YAML frontmatter for discoverability:

```yaml
---
name: skill_name
description: One-line summary of what the skill does.
---
```

Then include:

1. **Title** - Skill name as H1 header (must match directory name)
2. **Description** - One-line summary of what the skill does
3. **Core Content** - The main instructions, commands, or guidance
4. **Sections** - Organized by topic with H2 headers

## Best Practices

### 1. Design for Context Efficiency

Skills are loaded into Claude's context window. Keep them:
- **Concise** - Include only essential information
- **Scannable** - Use tables, lists, and code blocks
- **Actionable** - Focus on commands and procedures, not explanations

### 2. Use the 3-File Pattern

| File | Purpose | Content |
|------|---------|---------|
| `SKILL.md` | Core knowledge | Essential commands and concepts |
| `examples.md` | Learning | Step-by-step workflows |
| `reference.md` | Quick lookup | Tables, cheatsheets |

### 3. Include Templates

For repetitive tasks, provide templates in `templates/` directory:
- Job scripts
- Config files
- Boilerplate code

### 4. Write for Search

Use clear, searchable headings:
- "## Job Submission" not "## How to Submit"
- "## GPU Jobs" not "## Using Graphics Cards"

### 5. Prefer Tables Over Prose

Tables are scannable and dense:

```markdown
| Command | Description |
|---------|-------------|
| `cmd1` | Does X |
| `cmd2` | Does Y |
```

### 6. Use Consistent Code Blocks

Always specify the language:

```bash
# Shell commands
command --flag value
```

```python
# Python code
def example():
    pass
```

## Creating a New Skill

1. Create the directory structure:
   ```bash
   mkdir -p skills/my_skill/templates
   ```

2. Create `SKILL.md` with:
   - H1 title matching directory name
   - Brief description
   - Core commands/concepts

3. Add `examples.md` with real-world workflows

4. Add `reference.md` with quick-lookup tables

5. Add templates for common tasks

## Installation Locations

Skills can be installed globally or kept in a local repository.

### Global Skills (`~/.claude/skills/`)

Available in all Claude Code sessions:

```bash
cp -r skills/my_skill ~/.claude/skills/
```

### Local Repository Skills

Keep skills in a git repository for version control and sharing:

```
my_skills_repo/
├── .claude/
│   └── settings.json    # Register skills path
└── skills/
    └── my_skill/
        └── SKILL.md
```

Create `.claude/settings.json` in your repo root:

```json
{
  "skills": {
    "paths": ["skills"]
  }
}
```

Or add to existing project:

```json
{
  "skills": {
    "paths": [".claude/skills"]
  }
}
```

Skills are discovered when Claude Code runs in that directory.

### Comparison

| Method | Use Case |
|--------|----------|
| Global (`~/.claude/skills/`) | Personal tools, always available |
| Local repo | Project-specific, shareable, version-controlled |

## Skill Naming

- Use `snake_case` for directory and file names
- Keep names short but descriptive
- Prefix with domain if needed (e.g., `aws_lambda`, `docker_compose`)