# Creating Claude Code Skills

> Guide for creating effective Claude Code Agent Skills. Use when users want to create, improve, or troubleshoot Skills that extend Claude's capabilities with specialized workflows, domain expertise, or tool integrations. Use when this capability is needed.

- Skill: `tomevault-io/creating-claude-code-skills` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/creating-claude-code-skills`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/creating-claude-code-skills/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/creating-claude-code-skills

---


# Creating Claude Code Skills

Skills are modular packages that extend Claude's capabilities with specialized knowledge, workflows, and tools.

## Quick Start

```
my-skill/
├── SKILL.md              # Required: metadata + instructions
├── reference.md          # Optional: detailed docs
└── scripts/              # Optional: utility scripts
    └── helper.py
```

## SKILL.md Structure

```yaml
---
name: skill-name          # lowercase, hyphens, max 64 chars
description: What it does and when to use it. Max 1024 chars.
---

# Skill Name

## Instructions
Clear, step-by-step guidance.

## Examples
Concrete input/output examples.
```

## Core Principles

1. **Be Concise**: Claude is smart. Only add context Claude doesn't already have.
2. **Progressive Disclosure**: SKILL.md is overview. Details go in separate files.
3. **Match Freedom to Risk**: Fragile operations need specific scripts; flexible tasks need general guidance.

## Writing Effective Descriptions

The `description` field is critical for discovery. Include:
- What the skill does
- When to use it (triggers/contexts)
- Key terms users would mention

**Good**:
```yaml
description: Extract text from PDF files, fill forms, merge documents. Use when working with PDF files, forms, or document extraction.
```

**Bad**:
```yaml
description: Helps with documents
```

## File Organization Patterns

**Simple skill** (single file):
```
commit-helper/
└── SKILL.md
```

**Skill with references**:
```
pdf-processing/
├── SKILL.md           # Quick start + navigation
├── FORMS.md           # Form-filling details
└── REFERENCE.md       # API reference
```

**Skill with scripts**:
```
data-analysis/
├── SKILL.md
├── scripts/
│   └── validate.py
└── references/
    └── schema.md
```

## Key Guidelines

- Keep SKILL.md under 500 lines
- Use forward slashes in paths: `scripts/helper.py`
- Keep references one level deep from SKILL.md
- Use third person in descriptions
- Test with all models you plan to use

## Skill Locations

- **Personal**: `~/.claude/skills/skill-name/`
- **Project**: `.claude/skills/skill-name/`

For detailed patterns, see [references/patterns.md](references/patterns.md).
For anti-patterns to avoid, see [references/anti-patterns.md](references/anti-patterns.md).

---
> Source: [ingen084/KyoshinEewViewerIngen](https://github.com/ingen084/KyoshinEewViewerIngen) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-23 -->