0 / 13 checks

Author your first agent skill.

40 minutes

By the end, you'll be able to:

  • Explain what Agent Skills are and when to use them.
  • Decide what belongs in each part of an Agent Skill: description, instructions, and supporting files.
  • Write Agent Skill descriptions that help agents know when to use them.
  • Build and test a working Agent Skill, then improve it based on how the agent responds to real requests.

Read this once, then build. A skill is just a reusable playbook for work you keep explaining to an agent.

Use it for repeats

If you paste the same steps, rubric, template, or checklist more than once, it is skill-shaped.

Name one job

A good skill does one recognizable task and produces one clear kind of output.

Description triggers

The agent sees the name and description first, so the description must say what it does and when to use it.

Files stay separate

Keep the main instructions short. Put long examples, templates, assets, or deterministic code in supporting files.

LAB

Build your first skill.

Start with Step 01. Steps 02 and 03 unlock after you choose the skill name, what it produces, and when the agent should use it.

01

Design YOUR skill for a real workflow.

Pick a workflow from your job, something you currently re-explain to the agent every time you ask. We'll suggest a real starter for a skill in your role.

1 Pick your role.
02

Draft the SKILL.md

@skill-creator, $skill-creator, skill editor, or project folder

If your environment has a built-in skill creator, start there: use @skill-creator in ChatGPT Work or $skill-creator in Codex. Otherwise, use a skill editor or create a folder with a required SKILL.md file.

The prompt below turns your Step 01 decisions into the required frontmatter, the workflow body, and any supporting files the skill should bundle.

Open in ChatGPT
I designed this starter agent skill in the lesson. Use the name and description below as the starting point. Name: [generated skill name] Description: [generated skill description] Create a portable Agent Skill package in the Agent Skills format. Return the draft in three sections: - SKILL.md frontmatter: name and description - SKILL.md body: imperative workflow steps, expected inputs and outputs, ask/stop rules, and quality checks - Supporting files: references/, scripts/, or assets/ only if they are needed Use instructions over scripts unless deterministic behavior or external tooling is required. Move long examples, templates, schemas, or style guides out of SKILL.md and into supporting files. If the workflow needs live data, account access, or controlled actions, list the required tool or MCP dependency instead of pretending the skill can access it by itself. If you need details before drafting, ask no more than three follow-up questions.

Your platform may ask follow-up questions, generate draft files, or leave you to create files manually. Before saving or installing, check that the description names both what the skill does and when the agent should use it.

03

Test, edit, and iterate

test in the runtime; revise in the editor

Open the skill you just created in your platform's skill editor, project workspace, or local folder. Then run it in the agent environment. Test a small prompt set: one direct request, one indirect request, one messy real-user phrasing, and one nearby but out-of-scope request that should not activate the skill.

Test loop Prompt the agent → observe whether the skill activates → inspect output quality → revise description, instructions, or resources → retest.

Use whatever test surface your platform provides: a side-by-side skill editor, a preview chat, a command-line run, or a staging agent.

Watch what happens. Each test prompt produces one of four signals; click each to see what it means and what to fix.

Edit on the left, save, re-run the failing prompts on the right. Make one round of edits. A skill tightened around real failures generalizes better than one that grew to handle every imagined edge case.

Your skill is ready when…
Naming & description
  • The name is lowercase, hyphenated, and matches the skill folder name.
  • The description says what the skill produces, tightly enough that the runtime can match it against a real request.
  • The description says when to use it, including the indirect phrasings real users will type.
Activation behavior
  • The skill activates on direct, indirect, and messy prompts a real user would write.
  • The skill does not activate on 1 nearby but out-of-scope prompt.
  • The output follows the intended structure, and incomplete inputs trigger a follow-up question.
Resource organization
  • Long examples or multi-row templates the body would otherwise have to reproduce live in references/, cited from the body.
  • Any deterministic logic the skill depends on (parsing, conversions, validation) lives in scripts/, called from the body.
  • Static files the skill returns or reuses (images, sample data, fonts) live in assets/.

Click each one to tick it off against the skill you just built. Any miss is a real edit, not a checkbox to argue with.

Worked example Curious what a finished SKILL.md can look like? Open the MCQ Quality Coach example skill on GitHub. It shows how a final SKILL.md can name a skill, describe when to use it, and give the agent reusable instructions.
· · ·

Inside a skill package

You built a skill in the lab. Now look at the package shape most agent systems use: metadata that helps the runtime decide when to use the skill, an instruction body that tells the agent how to do the work, and optional resources such as templates, examples, scripts, or assets. In this lesson, a SKILL.md-style file is the concrete example; in other environments, the same roles may live in YAML, JSON, a settings panel, or a project folder.

Portable pattern Treat SKILL.md as one implementation of a broader skill-package pattern. The same design decisions transfer across platforms: concise metadata for discovery, focused instructions for activation, and separate resource files for long or reusable material.
EXERCISE

Click the part of this example SKILL.md that holds the name.

Anatomy of a skill Diagram of a SKILL.md file showing four labeled regions on the right side: NAME and DESCRIPTION in the frontmatter (top), INSTRUCTIONS and RESOURCES in the body (bottom). Each label has a leader line pointing to its location in the file. SKILL.md --- name: meeting-notes-summarizer description: Turn raw meeting transcripts or notes into a structured summary with decisions, owners, and dates. Use when the user pastes meeting notes or asks to recap a call or summarize a meeting. --- # Meeting notes summarizer Produce a tight, scannable recap of a meeting… ## How to produce the summary 1. Read the entire input first… 2. Identify participants… 3. Extract three sections, using the template at references/template.md ## Output rules - Keep it under 200 words. - Preserve names, dates, numbers. - Flag uncertainty with "Possibly:". ① NAME lowercase, hyphenated identifier ② DESCRIPTION what + when, with trigger phrases ③ INSTRUCTIONS the procedure the agent follows ④ RESOURCES files the body cites FRONTMATTER BODY
YOUR SCORE · 0 of 4 found on first try

You've seen the rules: metadata always loaded into context, body loaded on activation, resources loaded only when the body cites them. The decision you'll face in your own skills is which level each new piece of content belongs in. Get this wrong and your skill bloats or fails to activate.

EXERCISE

Place each piece of content in the right folder.

Drag a card to a zone, or tap a card then a zone. Wrong placements bounce back with a hint.

The 5-step procedure for producing a meeting summary
A 200-line example transcript showing edge-case handling
Trigger phrases users say to invoke this skill
A Python helper that calls the Linear API to create tickets
Behavioral rule: "never invent action items the meeting did not discuss"
meeting-notes-summarizer/
L1
Metadata
name + description
L2
Instructions
instruction body
L3+
Resources
references/, scripts/, assets/
YOUR SCORE · 0 of 5 placed correctly on first try

You've designed your skill in the lab and placed each part of SKILL.md in the right slot. Next: see what the agent actually does at the moment a skill is supposed to activate, what loads, what doesn't, and why that matters for cost and latency.

· · ·
UNDER THE HOOD

How agent skills work.

You've built a working skill. Now zoom out: here's why it works that way, and why a package of instructions and resources is more scalable than a saved prompt.

Why skills, instead of prompts or custom assistants.

Saved prompts and custom assistants solve part of the problem of repeatable work, but each one shifts what you do each time:

Saved prompt

Each time, you:

Find it, copy, paste, edit.

Lives in a doc or notes app. You manage finding and updating it.

What enters contextNothing automatic. Whatever you paste in is what the agent sees, every time.

Custom assistant

Each time, you:

Switch to that assistant, then ask.

One assistant usually covers one broad task or persona. Scaling to many team workflows gets hard to manage.

What enters contextThe assistant instructions are active whenever you use that assistant, plus any retrieved knowledge the platform chooses to include.

Skill

Each time, you:

Just ask in normal language.

The agent picks the right skill on its own and runs the procedure.

What enters contextJust the name and description up front. The body loads only when the skill matches; resources load only when the body cites them. Progressive disclosure.

Skills change what the agent does, not just what you do. Fifty skills installed add only modest discovery overhead compared to five, because the heavy lifting (the body) only loads for whichever skill the user's request actually matches.

The skill you just built has a specific shape. The folder you installed or drafted is the basic anatomy of every skill: a required SKILL.md file and optional bundled resources.

my-skill/ a folder on disk
  • SKILL.md Required

    Two parts: frontmatter (name + description) and body (the instructions for the agent).

  • references/ Optional

    Long examples, format specs, reference tables.

  • scripts/ Optional

    Executable code (Python, shell, and so on).

  • assets/ Optional

    Templates, fixtures, and other static files.

Two things make this work as an architecture: which parts the agent knows about, and which parts it actually loads. Here's that split.

When each piece loads.

Skills load in three gated stages, a pattern called progressive disclosure. A workspace can hold dozens of skills cheaply because most stay cold until needed.

A note on tokens: tokens are roughly the units of text the model processes; ~100 tokens is about a sentence, 5,000 tokens is about 8 pages. Smaller numbers mean faster, cheaper responses.

L1

Metadata

Discovery
When loaded
Always loaded into context, for every available skill in the workspace
Token cost
~100 tokens per skill
Content
name + description from frontmatter
You author
The frontmatter
if the skill's description matches the user's request
L2

Instructions

Activation
When loaded
When the skill is triggered
Token cost
Under 5,000 tokens (recommended)
Content
The SKILL.md body: the procedure
You author
The instructions
if the body cites a file
L3+

Resources

Execution
When loaded
As needed, only when the body cites them
Token cost
Pay only when cited
Content
Files in scripts/, references/, assets/
You author
The bundled files
SIMULATION

Predict which Skill activates, then watch what loads.

User: "this vendor wants to give us a quote for a thing we don't need, can you help me say no nicely?"
Context window
L1 Discovery every available skill's metadata is always loaded in context
  • vendor-quote-comparator · compares vendor quotes on cost, terms, and delivery and outputs a ranking
  • vendor-decline-writer · drafts polite emails declining vendor pitches, quotes, or unsolicited sales outreach
  • feedback-softener · rewrites blunt feedback into diplomatic versions for performance reviews and team comms
if the description matches the user's request
L2 Activation awaiting… matched skill's body loads
    if the body cites a file
    L3+ Execution awaiting… cited files load
      On disk
      vendor-quote-comparator/
      • SKILL.md
      • references/
      • scripts/
      vendor-decline-writer/
      • SKILL.md
      • references/
      • scripts/
      feedback-softener/
      • SKILL.md
      • references/
      • scripts/
      KNOWLEDGE CHECK
      UNANSWERED
      A workspace has 12 skills installed. A user asks, "Can you help me write a polite decline to this vendor pitch?" Which of the following is true at the moment the agent decides what to do?
      • AThe agent loads the full instruction body of every installed skill so it can compare them and pick the best fit.
        Incorrect. This is the load-everything misconception. Loading all 12 bodies would burn ~60,000 tokens every turn. At discovery, only the lightweight metadata (name + description) is loaded; the body of a skill loads only at activation, and only for the matched skill.
      • BThe agent has only the name and description of each skill in context, then loads the body of whichever skill's description matches the request.
        Correct. All 12 names and descriptions are loaded into context up front (~100 tokens each). The agent matches the prompt against those descriptions, then loads the body of whichever skill matches. The other 11 stay on disk; their bodies never enter context.
      • CThe agent scans every file in every skill folder, including references/ and scripts/, to figure out which skill is most relevant.
        Incorrect. Resources never load before a match. Files in references/ and scripts/ only enter context during execution, after a skill activates and its body cites them. Discovery happens entirely on metadata; resources are downstream.
      · · ·
      EXERCISE

      Diagnose failures.

      The three layers you just placed, description, body, resources, are also the three places a skill can fail. The symptom tells you which one. You'll diagnose someone else's skill here, then carry the same pattern back to your own when it misbehaves. Three colleagues tried Sam's weekly-update-drafter skill (a communications skill that turns rough bullet points into the team's standard weekly update). For each result, decide which layer Sam needs to edit, the same call you'll make next time your own skill produces something wrong.

      1. 01
        Priya typed: "weekly update from these bullets"
        Result: The skill activated and wrote the update, but the priority-tier table used invented labels (Urgent / Soon / Later) instead of the team's canonical tiers. The file references/priority-tiers.md was never loaded.
      2. 02
        Janelle typed: "can you turn these notes into our weekly update?"
        Result: The agent wrote a generic summary. The skill never activated.
      3. 03
        Marcus typed: "draft this week's update from these bullets"
        Result: The skill activated. The draft had Wins, In-progress, and Blockers sections, but skipped the Asks section the team requires.
      · · ·
      KNOWLEDGE CHECK

      Check your understanding.

      Four questions. Take your time, this isn't graded.

      QUESTION 01
      UNANSWERED
      The agent is about to decide whether to use your meeting-notes-summarizer skill for a user's request. Before that decision is made, which content from your skill is loaded into context?
      • AOnly the name and description from the frontmatter.
        Correct. Progressive disclosure in action: every available skill's metadata (name + description, around 100 tokens) is always loaded into context so the runtime can match the request against the catalog. Only after the match does the full body load. Everything else stays on disk until execution.
      • BThe frontmatter plus the first paragraph of the body, as a preview to help with the matching decision.
        Incorrect. There's a sharp boundary between matching and using a skill, not a graduated one. Either the agent has activated the skill and read the full body, or it hasn't. The first paragraph isn't a special preview tier.
      • CThe full SKILL.md, including frontmatter and body, but not any files in references/.
        Incorrect. That's close to how it works after the agent has decided to use the skill. The question asks what's loaded before that decision. Try the option that loads less.
      QUESTION 02
      UNANSWERED
      A teammate's skill has the description: "skill for converting CSV data into clean, formatted reports." They've shipped it but it's almost never activating. Which rewrite gives the biggest gain?
      • A"Convert CSV data into clean, formatted reports for downstream analysts to review and share with stakeholders."
        Incorrect. This is WHAT only. It describes what the skill produces but says nothing about when a user would invoke it. The agent would have to infer the situation from scratch. Look for an option that names both required pieces.
      • B"Convert a CSV into a formatted report with summary stats. Use when the user shares a CSV or asks to 'analyze', 'visualize', or 'report on' tabular data."
        Correct. Both required pieces are named: WHAT the skill does ("formatted report with summary stats") and WHEN to use it ("user shares a CSV"). The WHEN is grounded in trigger phrases users actually say ("analyze", "visualize", "report on") rather than left abstract.
      • C"Convert CSV data into a comprehensive report. This skill is for users who have CSV files and need to analyze, summarize, or visualize their tabular data. The output includes summary statistics where appropriate, formatted output for downstream review by analysts or stakeholders, and handles standard CSV formats with headers."
        Incorrect. The verbose-description trap. WHEN signals are present but buried in expository padding ("CSV files", "tabular data", "downstream review by analysts"), which dilutes the match. Every word here loads on every conversation at discovery; padding the agent with context it already has burns tokens without improving activation. Tight WHAT plus explicit trigger phrases beats verbose context every time.
      QUESTION 03
      UNANSWERED
      Your skill must calculate quiz item difficulty from a CSV and flag any distractor selected by more than 30% of learners. Where should that deterministic calculation live?
      • AIn the description, with the formula written into the trigger text.
        Incorrect. The description should help the agent decide when to use the skill. It is not the place for formulas, calculations, or implementation details.
      • BIn the SKILL.md body, with prose steps the model repeats each time.
        Incorrect. The body should explain the workflow, but exact CSV calculations are better handled by code. Prose invites inconsistency when the logic must be repeatable.
      • CIn scripts/, with SKILL.md telling the agent when to run it.
        Correct. Deterministic parsing, calculations, conversions, and validation belong in scripts/. The body should call the script at the right moment and interpret the output.
      QUESTION 04
      UNANSWERED
      A skill should turn meeting action items into real Linear tickets in the team's workspace. What is the right boundary between the skill and the connected tool?
      • APut the Linear API steps and an access token directly in SKILL.md.
        Incorrect. SKILL.md should not carry secrets or pretend to authorize external actions. The skill can describe the workflow, but the connected tool handles controlled access.
      • BUse the skill for the workflow and required fields; use a connected tool or MCP server to create tickets.
        Correct. The skill teaches the agent when to create tickets, what fields to collect, and how to handle ambiguity. The connected tool performs the authorized action.
      • CAvoid skills because any workflow touching external systems must be a custom assistant.
        Incorrect. Skills can guide tool-backed workflows. The key is keeping the workflow instructions in the skill and the live, authorized action in the connected tool.
      BADGE
      Skill Author I
      LOCKED
      0 / 13 checks
      Complete the activities on this page to earn the Skill Author I badge.