Agent Skills Basics

10 examples to get you started with Agent Skills - 7 basic and 3 intermediate.

Prerequisites

• Access to a Claude surface that supports Skills - Claude Code, Cowork, or claude.ai.
• No special install beyond your normal Claude account and plan - Skills are a feature of the surface, not a separate product.
• A recurring task in mind is the best starting point: a report format, a checklist, a naming convention, or any process you find yourself re-explaining.

Basic Examples

1. Recognizing a Task Worth Turning Into a Skill

Not every one-off question needs a Skill - the good candidates are tasks you repeat with the same shape every time.

Signs a task is a good first Skill:
- You've explained the same steps or format to Claude more than twice.
- The output needs to follow a specific structure every time (a report, a checklist, a template).
- Someone else on your team would benefit from the same instructions.

• A Skill pays off on repetition - a task you'll only ever do once isn't worth packaging.
• The clearest first Skills are ones with an obvious trigger phrase, like "weekly report" or "code review."
• If you can't describe in one sentence when you'd want it to fire, it's worth narrowing the idea before building it.
• Recurring reports, review checklists, and onboarding walkthroughs are the most common starting points teams reach for.

2. Creating a Skill Folder

A Skill starts as a folder with a single required file inside it, named SKILL.md.

Minimal Skill folder:
weekly-report/
  SKILL.md

• The folder name doesn't have to match anything exactly, but a short, descriptive name makes your Skill library easier to scan later.
• SKILL.md is the only required file - everything else in the folder is optional.
• Where this folder lives depends on the surface: a project-level Skills location in Claude Code, a Skills area in Cowork, or a Skills section in your claude.ai settings.
• You don't need to restart a conversation for a new Skill to become available - once it's added, Claude can find it on the next matching task.

3. Writing the Frontmatter

SKILL.md opens with a short metadata block that tells Claude what the Skill is and when to use it.

---
name: weekly-report
description: >-
  Generates the weekly team status report in our standard format.
  Use when asked for a weekly update, status report, or team summary.
---

• name is a short identifier for the Skill - keep it lowercase and specific.
• description is the field Claude actually matches against incoming tasks, so it needs to state both what the Skill does and when it applies.
• A description that only says what the Skill does, without naming when to use it, is the single most common reason a Skill goes unused.
• Two or three concrete trigger phrases in the description - the words a person would actually type - work better than a single abstract category name.

4. Writing the Instructions Body

Below the frontmatter, the rest of SKILL.md is plain-language instructions for how to do the task.

Body of SKILL.md (after the frontmatter):
1. Pull the three headline updates from this week's notes.
2. Group them under Wins, Risks, and Next Steps.
3. Keep each bullet to one sentence.
4. End with a one-line summary for leadership.

• Write the body the way you'd explain the task to a capable new teammate - specific steps, not vague goals.
• Numbered steps work well for processes; plain prose works well for style or tone guidance.
• You can be as detailed as the task needs - the body only loads when the Skill is triggered, so length here doesn't slow down unrelated conversations.
• Keep the instructions focused on one task; a Skill trying to cover several unrelated jobs gets harder for Claude to match reliably.

5. Giving Claude a Task That Matches

Once a Skill exists, you don't invoke it by name - you just ask for the task, and Claude checks it against your Skills.

Example message:
"Can you put together this week's status report?"

• If the wording in your message overlaps with the Skill's description, Claude loads its instructions before answering.
• You never have to say "use the weekly-report Skill" - that defeats the point of automatic discovery.
• The first time you test a new Skill, use the exact kind of phrasing you expect to use in real requests, not a generic test sentence.
• If the reply doesn't follow the Skill's format, that's a sign to revisit the description or instructions, not a sign Skills don't work.

6. Confirming a Skill Was Used

Most surfaces show some indication that a Skill loaded, so you're not left guessing whether it fired.

What to check:
- Does the output follow the structure you wrote in the Skill's body?
- Does the surface show a Skill indicator or reference in the response?
- Does asking "which Skill did you use for that?" get a straight answer?

• The most reliable check is simply whether the output matches what you wrote in the Skill - if it does, it fired.
• Asking Claude directly which Skill it used is a legitimate way to confirm, especially while you're still testing a new one.
• If a Skill isn't firing when it should, the description is the first place to look, not the body instructions.
• This kind of quick check is worth doing right after creating any new Skill, before you rely on it for real work.

7. Editing a Skill After the Fact

Skills aren't fixed once created - you can open SKILL.md and revise the instructions or description any time.

Common early edits:
- Tightening the description after noticing the Skill didn't trigger.
- Adding a step you forgot the first time.
- Removing an instruction that produced the wrong format.

• There's no separate "publish" step - saving the edited file is enough for the next matching task to use the new version.
• Early on, expect to revise the description more than the body - getting Claude to reliably recognize the trigger is usually the harder part.
• Small, specific edits after watching one real result are more effective than trying to write a perfect Skill on the first attempt.
• Keeping a Skill in one place means an edit updates it everywhere that Skill is used, rather than needing to fix scattered copies.

Intermediate Examples

8. Bundling a Reference File

A Skill's folder can hold more than SKILL.md - additional files travel with it and can be referenced from the instructions.

Skill folder with a reference file:
weekly-report/
  SKILL.md
  report-template.md

• Move long, detailed material - like a full template or style guide - into a separate reference file, and keep SKILL.md's body focused on the steps.
• This keeps the main instructions easy to scan while still giving Claude access to as much detail as the task needs.
• Reference files are optional; most simple Skills never need one.
• This is also where a small script can live, if the Skill's allowed-tools scope permits Claude to run it.

Related: Anatomy of a SKILL.md File - what belongs in the frontmatter versus the body versus a bundled file

9. Writing a Description That Triggers Reliably

The description field is worth a second pass once you've seen how the Skill behaves in practice.

Before: "Handles reports."
After: "Generates the weekly team status report in our standard
format. Use when asked for a weekly update, status report, or
team summary."

• A vague description like "handles reports" gives Claude very little to match against and often goes unused.
• The revised version states what the Skill does and lists the specific phrases a person would actually type to ask for it.
• If two Skills' descriptions overlap heavily, Claude may pick the wrong one - narrowing each description reduces that risk.
• This is the single highest-leverage edit you can make to a Skill that isn't firing when expected.

Related: How Claude Discovers and Loads Skills Automatically - the mechanics behind why description wording matters this much

10. Using the Same Skill Across Surfaces

A Skill built once is not tied to a single Claude surface - the same folder works the same way in Claude Code, Cowork, and claude.ai.

One Skill, three surfaces:
- Claude Code: fires while working in a repository.
- Cowork: fires during a team workspace task.
- claude.ai: fires in an ordinary chat conversation.

• You don't need a separate version of a Skill for each surface - the description-matching mechanism behaves the same everywhere.
• This makes Skills a good place to put team conventions you want followed consistently, regardless of which surface someone is working in.
• Where the Skill is stored, and how it's enabled, differs slightly per surface - the Skill's content and behavior once loaded do not.
• If a Skill works well in one surface but not another, the cause is almost always an enablement setting, not the Skill itself.

Related: Enabling and Managing Skills Across Claude Code, Cowork, and Claude.ai - where to turn Skills on per surface

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.