Back to library

What's a Claude Skill?

Skills are small folders of instructions (and optional scripts) that Claude loads on demand. They turn Claude into a specialist for whatever domain you keep solving over and over — NetSuite searches, SOX controls, cutover checklists, you name it.

Loaded automatically

Claude reads each skill's description and pulls in the matching one when it's relevant.

Markdown, not magic

Every skill is a SKILL.md with YAML frontmatter and plain instructions.

Bundle resources

Drop scripts, templates, or reference docs alongside SKILL.md and Claude can use them.

The anatomy of a skill

A skill is just a folder. The only required file is SKILL.md:

my-skill/
├── SKILL.md          # required — instructions + frontmatter
├── scripts/          # optional — runnable helpers
│   └── helper.py
└── reference/        # optional — docs Claude can read on demand
    └── notes.md

Required frontmatter

  • name — kebab-case identifier, must match the folder name.
  • description — one or two sentences telling Claude when to use it. This is what triggers the skill, so be specific about the situations and keywords.

Body of SKILL.md

Plain markdown. Conventions that work well:

  • When to use — restating the trigger conditions in human terms.
  • Instructions — the steps Claude should follow.
  • Examples — input/output pairs that anchor the behavior.
  • Resources — list of bundled scripts or files Claude may load.

Example

---
name: netsuite-saved-search-helper
description: Use when the user asks to draft, review, or troubleshoot NetSuite saved searches. Covers search criteria, formula columns, and result filtering.
---

# NetSuite Saved Search Helper

## When to use this skill
Trigger when the user mentions saved searches, search criteria, or NetSuite reporting tasks.

## Instructions
1. Ask for the record type if not provided.
2. Suggest criteria as filters first, then formulas only when needed.
3. ...

## Resources
- scripts/validate-search.py — quick validator for exported searches

Installing a skill

Claude Code (CLI)

Drop the folder into one of:

  • ~/.claude/skills/<name>/
  • .claude/skills/<name>/ (project-scoped)

Claude picks it up on the next session.

claude.ai / API

Zip the skill folder and upload it under Settings → Capabilities → Skills, or attach it via the Agent Skills API.

Good skills, bad skills

  • ✅ Narrow, specific triggers in the description.
  • ✅ Step-by-step instructions, not vibes.
  • ✅ Real examples from work you've actually done.
  • ❌ No client names, secrets, or proprietary configs.
  • ❌ Avoid kitchen-sink skills — split by task, not by domain.
Share one of yours →