# Creating Skills

> Creates Claude Code skills with proper structure, naming, and best practices. Use when the user asks to create a new skill, wants help writing a SKILL.md, or needs to structure skill content.

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

---


# Creating Skills

Skills extend Claude's capabilities with domain-specific knowledge and workflows.

## Structure

```
skill-name/
├── SKILL.md              # Required: metadata + instructions
├── reference.md          # Optional: detailed docs (loaded on demand)
└── scripts/              # Optional: utility scripts
```

## SKILL.md Template

````markdown
---
name: doing-the-thing
description: Does X and Y. Use when the user asks about Z or needs to accomplish W.
---

# Skill Title

One-line summary of what this skill does.

## Quick Start

```bash
# most common usage
```

## When to Use

- Trigger condition 1
- Trigger condition 2

## Workflow

1. First step
2. Second step
3. Verify result
````

## Frontmatter Rules

| Field | Constraints |
|-------|-------------|
| `name` | Max 64 chars, lowercase + hyphens only, no "anthropic" or "claude" |
| `description` | Max 1024 chars, third person, what it does + when to use it |

**Naming**: Use gerund form (`processing-pdfs`, `analyzing-data`) or action form (`process-pdfs`).

## Key Principles

**Be concise** - Claude already knows general concepts. Only add what's unique to this skill.

```markdown
# Bad: 150 tokens explaining PDFs
PDF (Portable Document Format) files are a common file format...

# Good: 50 tokens, actionable
Use pdfplumber for text extraction:
```

**Set freedom appropriately**:
- High freedom: "Analyze the code and suggest improvements"
- Low freedom: "Run exactly: `python scripts/migrate.py --verify`"

**Write in third person**:
- Good: "Extracts text from PDF files"
- Bad: "I can help you extract text" / "You can use this to extract"

## Workflow Pattern

For multi-step tasks, provide a checklist:

````markdown
## Processing Workflow

```
Progress:
- [ ] Step 1: Analyze input
- [ ] Step 2: Transform data
- [ ] Step 3: Validate output
```

**Step 1: Analyze input**
Run: `python scripts/analyze.py input.pdf`

**Step 2: Transform data**
...
````

## Progressive Disclosure

Keep SKILL.md under 500 lines. Split large content:

```markdown
## Advanced Features

**Form filling**: See [FORMS.md](FORMS.md)
**API reference**: See [REFERENCE.md](REFERENCE.md)
```

Keep references one level deep from SKILL.md.

## Anti-Patterns

- Vague names: `helper`, `utils`, `tools`
- Time-sensitive info: "If before August 2025..."
- Too many options: "You can use pypdf, or pdfplumber, or PyMuPDF..."
- Windows paths: `scripts\helper.py` → use `scripts/helper.py`
- Deep nesting: SKILL.md → advanced.md → details.md

## Checklist

Before finalizing:

- [ ] Description is specific with trigger conditions
- [ ] Under 500 lines
- [ ] No time-sensitive content
- [ ] Consistent terminology
- [ ] Clear workflows with steps
- [ ] One level deep references

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/kxzk) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-14 -->