Skill Design & Packaging Basics

10 examples to get you started with Skill Design & Packaging - 7 basic and 3 intermediate.

Prerequisites

A repeated task you already ask Claude to do the same way more than once - this is the raw material, not a blank page.
A place to save a folder: a SKILL.md file plus, optionally, a few supporting files alongside it.
No special software beyond a text editor - SKILL.md is a plain Markdown file with a YAML frontmatter block at the top.

Basic Examples

1. The Minimum Viable SKILL.md

Every Skill needs exactly two things in its frontmatter: a name and a description.

---
name: pr-review-checklist
description: >-
  Reviews a pull request diff against a fixed checklist. Use when the user
  asks for a PR review, code review, or to check a diff before merging.
---

name is a short, kebab-case identifier for the Skill folder and file.
description is what Claude compares against a new task to decide whether this Skill applies - it is doing more work than any other field.
Everything below the frontmatter is the instruction body Claude follows once it decides to use the Skill.
A Skill with just these two fields plus a body is a complete, valid package.

2. Stating What the Skill Does

The first half of a good description names the task in concrete terms.

description: >-
  Summarizes a customer support transcript into a structured ticket:
  issue, steps taken, and resolution status.

Name the actual output, not a vague category - "structured ticket" beats "helps with support."
Avoid describing the Skill in terms only its author would recognize; write it the way a teammate would describe the task.
This half answers "what does this do," which is necessary but not sufficient on its own.
Keep it to one or two sentences - a description is metadata, not documentation.

3. Stating When the Skill Should Trigger

The second half names the situations that should activate the Skill.

description: >-
  Summarizes a customer support transcript into a structured ticket. Use
  when the user pastes a support conversation or asks for a ticket summary.

"Use when..." is a reliable, explicit pattern for the trigger half of a description.
Name the concrete signals a real task would show - a pasted transcript, a specific request phrase - not an abstract category.
A description that only says what the Skill does, without saying when, is the single most common reason a Skill goes undiscovered.
Test the trigger half by asking: would this wording also match a task the Skill is NOT meant to handle?

Related: Writing an Effective Skill Description That Claude Will Trigger On - a full deep dive on this exact field.

4. Writing the First Numbered Step

Instructions belong in the body as ordered steps, not as one long paragraph.

## Instructions
 
1. Read the full transcript provided by the user.
2. Identify the customer's core issue in one sentence.
3. List the troubleshooting steps already attempted, in order.

Numbering forces you to decide the actual order of operations, which loose prose lets you skip.
Each step should be doable on its own, without needing to re-read the whole paragraph to know what to do next.
Short, specific steps are easier for Claude to follow the same way every time than a single dense paragraph.
Draft steps in plain language first; you can tighten the wording once the order is right.

5. Finishing the Step List

A useful step list ends with a concrete output, not a vague wrap-up.

4. Note the current resolution status: open, pending, or resolved.
5. Output the four fields above as a short structured summary.

The last step should describe exactly what gets produced, so there's no ambiguity about when the Skill is "done."
Avoid open-ended final steps like "wrap up appropriately" - they invite inconsistent results across runs.
A step list with a clear ending is also easier to test: you know what a correct run looks like.
Five steps is a reasonable size for a first Skill; longer tasks can have more, but each one should still be a single, concrete action.

6. Choosing a Level (basic vs. advanced task)

Not every Skill needs extra machinery - most start simple.

---
name: weekly-status-draft
description: >-
  Drafts a weekly status update from raw meeting notes or bullet points.
  Use when the user asks for a status update, recap, or standup summary.
---
## Instructions
1. Read the raw notes or bullet points provided.
2. Group items into: shipped, in progress, blocked.
3. Draft three to five sentences per group.

A Skill with just frontmatter and a short numbered list is a complete package - you don't need allowed-tools or bundled files to start.
Add complexity only when the task actually calls for it, not by default.
This is the shape most first Skills should take: two frontmatter fields and a handful of steps.
You can always add scoping or bundled resources later without rewriting what already works.

7. Saving the Package as a Folder

A Skill lives in its own folder, named to match its name field.

pr-review-checklist/
  SKILL.md

The folder name and the name field should match, so the package is easy to identify at a glance.
A single-file Skill - just SKILL.md in its own folder - is a normal, finished package, not an unfinished one.
Nothing else is required until a task genuinely needs bundled reference files, scripts, or tool scoping.
This is the point where "idea" has become "package" - the folder is complete and ready to be tried against a real task.

Intermediate Examples

8. Testing the Trigger Before Trusting the Output

Before relying on a new Skill, check that it activates on the right tasks and stays quiet on the wrong ones.

Test 1 (should trigger):
  "Here's the transcript from the call with the client, can you
  summarize it into a ticket?"
 
Test 2 (should NOT trigger):
  "Can you summarize this news article for me?"

Run at least one task you expect to activate the Skill and one you expect not to, and confirm Claude makes the right call both ways.
A Skill that produces a great result once invoked is only half finished if it also fires on unrelated tasks, or never fires at all.
If Test 2 accidentally triggers the Skill, the description is too broad and needs tighter, more specific trigger language.
If Test 1 fails to trigger, the description likely doesn't state the "when" clearly enough, even if the "what" is accurate.

Related: Common Mistakes That Make a Skill Hard for Claude to Find or Use - a fuller list of trigger failures to check for.

9. Revising a Description After a Missed Trigger

When a Skill doesn't fire on a task it should have, the fix is almost always in the description, not the instructions.

# Before: too abstract to match real phrasing
description: >-
  Helps with support tickets.
 
# After: concrete outputs and concrete trigger language
description: >-
  Summarizes a customer support transcript into a structured ticket with
  issue, steps taken, and resolution status. Use when the user pastes a
  support conversation or asks to turn a conversation into a ticket.

Compare the exact wording of the missed request against the description - the gap usually points straight at the fix.
Widening a description slightly is often safer than rewriting it from scratch, since the working parts stay intact.
Keep a short log of missed or false triggers while you refine a new Skill - patterns show up faster than one-off fixes.
A description is never really "done" the first time; expect at least one revision after real use.

When two tasks share most of their steps, one Skill with a branch usually beats two separate packages.

## Instructions
1. Read the provided notes.
2. If the notes are from a single meeting, draft a status update
   (see step 3a).
3a. Group into shipped, in progress, blocked; draft 3-5 sentences per group.
3b. If the notes span a full week across multiple meetings, draft a
    weekly digest instead: one paragraph per project, ordered by priority.

A single branching Skill is easier to discover and maintain than two Skills with nearly identical descriptions competing for the same trigger.
Branches should be based on something concretely detectable in the input, like "single meeting" vs. "spans a week," not a subjective judgment call.
If the branches genuinely diverge in most of their steps rather than just the ending, that's a signal they should be separate Skills after all.
This pattern scales: a well-organized Skill can hold a few closely related branches without becoming unclear about when each one applies.

Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5. Model names, pricing, and product features move quickly - verify current specifics at platform.claude.com/docs before relying on them.

Skill Design & Packaging Basics

10 examples to get you started with Skill Design & Packaging - 7 basic and 3 intermediate.

Prerequisites

A repeated task you already ask Claude to do the same way more than once - this is the raw material, not a blank page.
A place to save a folder: a SKILL.md file plus, optionally, a few supporting files alongside it.
No special software beyond a text editor - SKILL.md is a plain Markdown file with a YAML frontmatter block at the top.

Basic Examples

1. The Minimum Viable SKILL.md

Every Skill needs exactly two things in its frontmatter: a name and a description.

---
name: pr-review-checklist
description: >-
  Reviews a pull request diff against a fixed checklist. Use when the user
  asks for a PR review, code review, or to check a diff before merging.
---

name is a short, kebab-case identifier for the Skill folder and file.
description is what Claude compares against a new task to decide whether this Skill applies - it is doing more work than any other field.
Everything below the frontmatter is the instruction body Claude follows once it decides to use the Skill.
A Skill with just these two fields plus a body is a complete, valid package.

2. Stating What the Skill Does

The first half of a good description names the task in concrete terms.

description: >-
  Summarizes a customer support transcript into a structured ticket:
  issue, steps taken, and resolution status.

Name the actual output, not a vague category - "structured ticket" beats "helps with support."
Avoid describing the Skill in terms only its author would recognize; write it the way a teammate would describe the task.
This half answers "what does this do," which is necessary but not sufficient on its own.
Keep it to one or two sentences - a description is metadata, not documentation.

3. Stating When the Skill Should Trigger

The second half names the situations that should activate the Skill.

description: >-
  Summarizes a customer support transcript into a structured ticket. Use
  when the user pastes a support conversation or asks for a ticket summary.

"Use when..." is a reliable, explicit pattern for the trigger half of a description.
Name the concrete signals a real task would show - a pasted transcript, a specific request phrase - not an abstract category.
A description that only says what the Skill does, without saying when, is the single most common reason a Skill goes undiscovered.
Test the trigger half by asking: would this wording also match a task the Skill is NOT meant to handle?

Related: Writing an Effective Skill Description That Claude Will Trigger On - a full deep dive on this exact field.

4. Writing the First Numbered Step

Instructions belong in the body as ordered steps, not as one long paragraph.

## Instructions
 
1. Read the full transcript provided by the user.
2. Identify the customer's core issue in one sentence.
3. List the troubleshooting steps already attempted, in order.

Numbering forces you to decide the actual order of operations, which loose prose lets you skip.
Each step should be doable on its own, without needing to re-read the whole paragraph to know what to do next.
Short, specific steps are easier for Claude to follow the same way every time than a single dense paragraph.
Draft steps in plain language first; you can tighten the wording once the order is right.

5. Finishing the Step List

A useful step list ends with a concrete output, not a vague wrap-up.

4. Note the current resolution status: open, pending, or resolved.
5. Output the four fields above as a short structured summary.

The last step should describe exactly what gets produced, so there's no ambiguity about when the Skill is "done."
Avoid open-ended final steps like "wrap up appropriately" - they invite inconsistent results across runs.
A step list with a clear ending is also easier to test: you know what a correct run looks like.
Five steps is a reasonable size for a first Skill; longer tasks can have more, but each one should still be a single, concrete action.

6. Choosing a Level (basic vs. advanced task)

Not every Skill needs extra machinery - most start simple.

---
name: weekly-status-draft
description: >-
  Drafts a weekly status update from raw meeting notes or bullet points.
  Use when the user asks for a status update, recap, or standup summary.
---
## Instructions
1. Read the raw notes or bullet points provided.
2. Group items into: shipped, in progress, blocked.
3. Draft three to five sentences per group.

A Skill with just frontmatter and a short numbered list is a complete package - you don't need allowed-tools or bundled files to start.
Add complexity only when the task actually calls for it, not by default.
This is the shape most first Skills should take: two frontmatter fields and a handful of steps.
You can always add scoping or bundled resources later without rewriting what already works.

7. Saving the Package as a Folder

A Skill lives in its own folder, named to match its name field.

pr-review-checklist/
  SKILL.md

The folder name and the name field should match, so the package is easy to identify at a glance.
A single-file Skill - just SKILL.md in its own folder - is a normal, finished package, not an unfinished one.
Nothing else is required until a task genuinely needs bundled reference files, scripts, or tool scoping.
This is the point where "idea" has become "package" - the folder is complete and ready to be tried against a real task.

Intermediate Examples

8. Testing the Trigger Before Trusting the Output

Before relying on a new Skill, check that it activates on the right tasks and stays quiet on the wrong ones.

Test 1 (should trigger):
  "Here's the transcript from the call with the client, can you
  summarize it into a ticket?"
 
Test 2 (should NOT trigger):
  "Can you summarize this news article for me?"

Run at least one task you expect to activate the Skill and one you expect not to, and confirm Claude makes the right call both ways.
A Skill that produces a great result once invoked is only half finished if it also fires on unrelated tasks, or never fires at all.
If Test 2 accidentally triggers the Skill, the description is too broad and needs tighter, more specific trigger language.
If Test 1 fails to trigger, the description likely doesn't state the "when" clearly enough, even if the "what" is accurate.

Related: Common Mistakes That Make a Skill Hard for Claude to Find or Use - a fuller list of trigger failures to check for.

9. Revising a Description After a Missed Trigger

When a Skill doesn't fire on a task it should have, the fix is almost always in the description, not the instructions.

# Before: too abstract to match real phrasing
description: >-
  Helps with support tickets.
 
# After: concrete outputs and concrete trigger language
description: >-
  Summarizes a customer support transcript into a structured ticket with
  issue, steps taken, and resolution status. Use when the user pastes a
  support conversation or asks to turn a conversation into a ticket.

Compare the exact wording of the missed request against the description - the gap usually points straight at the fix.
Widening a description slightly is often safer than rewriting it from scratch, since the working parts stay intact.
Keep a short log of missed or false triggers while you refine a new Skill - patterns show up faster than one-off fixes.
A description is never really "done" the first time; expect at least one revision after real use.

When two tasks share most of their steps, one Skill with a branch usually beats two separate packages.

## Instructions
1. Read the provided notes.
2. If the notes are from a single meeting, draft a status update
   (see step 3a).
3a. Group into shipped, in progress, blocked; draft 3-5 sentences per group.
3b. If the notes span a full week across multiple meetings, draft a
    weekly digest instead: one paragraph per project, ordered by priority.

A single branching Skill is easier to discover and maintain than two Skills with nearly identical descriptions competing for the same trigger.
Branches should be based on something concretely detectable in the input, like "single meeting" vs. "spans a week," not a subjective judgment call.
If the branches genuinely diverge in most of their steps rather than just the ending, that's a signal they should be separate Skills after all.
This pattern scales: a well-organized Skill can hold a few closely related branches without becoming unclear about when each one applies.

Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5. Model names, pricing, and product features move quickly - verify current specifics at platform.claude.com/docs before relying on them.

Skill Design & Packaging Basics

Search Documentation

Skill Design & Packaging Basics