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.

10. Combining Two Related Tasks Into One Skill

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.