skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)

mkdir -p plugin-name/skills/skill-name/{references,examples,scripts}
touch plugin-name/skills/skill-name/SKILL.md

---
name: skill-name
description: This skill should be used when the user asks to "specific phrase 1", "specific phrase 2", "specific phrase 3". Include exact phrases users would say that should trigger this skill. Be concrete and specific.
version: 0.1.0
---

description: This skill should be used when the user asks to "create a hook", "add a PreToolUse hook", "validate tool use", "implement prompt-based hooks", or mentions hook events (PreToolUse, PostToolUse, Stop).

description: Use this skill when working with hooks.  # Wrong person, vague
description: Load when user needs hook help.  # Not third person
description: Provides hook guidance.  # No trigger phrases

undefined

undefined

Ask: "Review my skill and check if it follows best practices"

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
├── agents/
└── skills/
    └── my-skill/
        ├── SKILL.md
        ├── references/
        ├── examples/
        └── scripts/

undefined

undefined

To create a hook, define the event type.
Configure the MCP server with authentication.
Validate settings before use.

You should create a hook by defining the event type.
You need to configure the MCP server.
You must validate settings before use.

description: This skill should be used when the user asks to "create X", "configure Y"...

description: Use this skill when you want to create X...
description: Load this skill when user asks...

Parse the frontmatter using sed.
Extract fields with grep.
Validate values before use.

You can parse the frontmatter...
Claude should extract fields...
The user might validate values...

description: Provides guidance for working with hooks.

description: This skill should be used when the user asks to "create a hook", "add a PreToolUse hook", "validate tool use", or mentions hook events. Provides comprehensive hooks API guidance.

skill-name/
└── SKILL.md  (8,000 words - everything in one file)

skill-name/
├── SKILL.md  (1,800 words - core essentials)
└── references/
    ├── patterns.md (2,500 words)
    └── advanced.md (3,700 words)

You should start by reading the configuration file.
You need to validate the input.
You can use the grep tool to search.

Start by reading the configuration file.
Validate the input before processing.
Use the grep tool to search for patterns.

undefined

**Why bad:** Claude doesn't know references exist

name: Skill Name

name: skill-name

**Why good:** Claude knows where to find additional information

skill-name/
└── SKILL.md

skill-name/
├── SKILL.md
├── references/
│ └── detailed-guide.md
└── examples/
└── working-example.sh

skill-name/
├── SKILL.md
├── references/
│ ├── patterns.md
│ └── advanced.md
├── examples/
│ ├── example1.sh
│ └── example2.json
└── scripts/
└── validate.sh

undefined