Lesson 3 of 8 · 6 min read

Write the task spec

Write your task as a skill file that both Claude and ChatGPT can follow.

A skill is a folder with one file

A skill is written instructions that an assistant follows every time it does a task. The format comes from the Agent Skills standard, which Anthropic first developed and then released as an open standard. A skill is a folder that holds one required file, named SKILL.md.

SKILL.md starts with a short header. The header needs two fields: a name and a description. Below the header come the instructions, written in plain language. A skill can also hold scripts, templates and reference files, but a first skill does not need them.

The same file works in more than one assistant. Claude reads it. OpenAI says its ChatGPT skills build on the same open standard. Google began rolling out skills in the SKILL.md format to the Gemini app on October 13, 2026. You write the spec once, and it travels.

Why the description matters most

An assistant does not read every skill in full before each reply. At first it reads only each name and description. When your request matches a description, it loads that skill’s full instructions. The Agent Skills standard calls this progressive disclosure.

So the description decides whether your skill runs at all. Say what the task is, when to use it, and what it is not for. A description that says "Helps with reports" will fire at the wrong moments, or not at all. One that names the report, its audience and its sources fires when you need it.

The "not for" clause matters as much as the rest. Assistants ship with their own built-in skills, and yours can compete with them. Naming what your skill is not for keeps it out of requests that belong elsewhere.

What goes in the instructions

Charles Cook at PostHog writes his scheduled prompts in four parts: the data sources, the output format, the tone, and when to stay silent. That structure suits a task spec well, and this course uses it.

Sources name exactly where the assistant should look, and for what period. Output names the sections, their order and a length limit. Tone says who reads the result and how it should sound. Silence covers what to do when there is nothing to report, so the assistant does not invent filler.

Add three rules to every spec in this course. The result is a draft, and the assistant never sends it. The assistant uses only numbers from the sources and never estimates. If a source is missing, the draft says so at the top. Lesson 6 adds more checks, but these three go in from the start.

One task per skill

Write one skill for each task. A skill that drafts the report, the follow-ups and the inbox summary needs a broad description, and broad descriptions trigger at the wrong moments. A failure in one part also hides inside the others.

Small skills are easier to test, to move between assistants and to retire. Dana’s report skill does one thing. When Dana automates the meeting follow-ups, that becomes a second skill in a second folder.

Dry-run the spec before you install it

Test the spec by hand before you install it. Open a new conversation and paste in the SKILL.md. Then paste last week’s real inputs: the notes, the log, the messages. Ask for the draft, and compare it with what you sent last week.

The dry run shows where the spec is vague. If the draft picks the wrong week, the sources need a date range. If it invents a number, the rule about numbers is missing or too weak. If it pads quiet sections, the silence rule needs work. Fix the spec, not the draft.

Run the dry run twice, on two different weeks. One good draft can be luck. Two good drafts from different inputs mean the spec carries the task, not your corrections in the chat.

When a skill does not run

Users of both assistants report skills that install but never run. The spec requires a name in lowercase words joined by hyphens. One user reported that a skill named "Review-Code" never triggered, because of its capital letters. Another found that installed ChatGPT skills stopped being available, and renaming and re-uploading them fixed it.

Three habits prevent most of these failures. Keep the name lowercase with hyphens. Make the description specific to one task. When you want a skill to run, name it in your request, for example "Use the larkfield-status-report skill". Naming it removes the guesswork.

Moving a skill between assistants

The file moves between assistants, but its connections do not. A skill that reads your calendar through a Claude connector needs the same calendar connected in ChatGPT, where OpenAI’s pages call connections apps or connectors. After you move a skill, connect its sources again, check that your plan covers each part, and test it.

Keep the file portable from the start. Use only the name and description fields in the header. Describe sources in plain words, such as "the shipment log in the Operations folder", rather than naming one product’s tools. Make the skill work from SKILL.md alone, without extra files.

If you built custom GPTs in the past, this is where they go next. OpenAI plans to retire custom GPTs on December 11, 2026 and replace them with plugins. A migrated GPT keeps its instructions as a skill. It loses its conversation history, its chosen model, its sharing settings and any custom actions.

Worked example · Larkfield Supply

Dana writes the status-report spec

Dana turns the Friday report into a skill, one part at a time. The finished file is the third prompt below.

  1. Dana names the skill larkfield-status-report, in lowercase with hyphens, and gives the folder the same name.
  2. Dana drafts the description: what the report is, who reads it, and when to use it.That answers the question you guessed at: An assistant reads only the name and one other field of each skill before it decides to load the rest. Guess: which field decides whether your skill runs?
    What would you do next?What should Dana add to the description before moving on?Think it through, then show the answer

    A "not for" clause. Without it, the skill could fire on customer emails or board reports. Dana adds: not for customer emails, board reports or monthly finance summaries.

  3. Dana lists three sources by name and limits them to the current week: the shipment log, the supplier updates document, and the team channel.
  4. Dana sets the output: four sections in a fixed order, under 300 words, in plain sentences.
  5. Dana adds the rules: draft only, numbers only from sources, flag missing sources, and "No change this week" for quiet sections.

The finished SKILL.md runs to about 25 lines. Dana reviews it with the second prompt below, which finds that the spec never says which week counts as "this week". Dana adds "Monday to Friday" to the sources line.

Starter prompts

  • Write my SKILL.md

    Interview me about a recurring task so you can write a SKILL.md file for it. Ask one question at a time. Cover: what the task produces and who reads it; the exact sources it reads and for what period; the sections of the output, their order and a length limit; the tone; what to do when there is nothing to report; and what the skill is not for. Then write the SKILL.md with a header holding only a name (lowercase, with hyphens) and a description. The description must say when to use the skill and what it is not for. Add these rules: the result is a draft and is never sent; use only numbers from the sources; say at the top if a source is missing.

  • Review my SKILL.md

    Review this SKILL.md before I install it:

[paste your SKILL.md]

List every problem you find under these headings: vague sources, a missing time period, an output format that is not fixed, no rule for missing data, no rule for when to stay silent, a description without a "not for" clause, and anything that names one product’s tools. Do not rewrite the file. List the problems and suggest one fix for each.

  • Example: Larkfield’s status-report skill

    ---
name: larkfield-status-report
description: Drafts the Friday status report for the Larkfield Supply leadership team from this week’s shipment log, supplier notes and team updates. Use when asked for the weekly or Friday status report. Not for customer emails, board reports or monthly finance summaries.
---

# Friday status report

## Sources
Read only these, for the current week (Monday to Friday):
1. The shipment log spreadsheet in the Operations folder.
2. The Supplier Updates document.
3. Team updates in the #ops-weekly channel.

## Output
A draft with four sections, in this order:
1. Headline: one sentence on the week.
2. Shipments: the on-time rate and any late orders, with order numbers.
3. Suppliers: delays or changes, with the supplier name and the expected date.
4. Decisions needed: anything the leadership team must decide, or "None this week".
Keep the draft under 300 words. Write plain sentences.

## Rules
- This is a draft for Dana to check. Never send it.
- Use only numbers that appear in the sources. Never estimate.
- If a source is missing or empty, say so at the top of the draft.
- If nothing changed in a section, write "No change this week".
- End with a list of the sources you read.

Steps for your assistant

In Claude

Checked on October 15, 2026

  1. Turn on code execution and file creation in Settings, under Capabilities.
  2. Save SKILL.md in a folder with the same name as the skill, then compress the folder into a ZIP file.
  3. Go to Customize, then Skills. Click the plus button, choose Create skill, then Upload a skill, and select the ZIP file.
  4. Make sure the skill is turned on. Test it twice: once by asking for the task in plain words, and once by naming the skill.

Anthropic’s help page lists skills on every plan, including Free. A folder name that does not match the skill name causes an upload error.

In ChatGPT

Checked on October 15, 2026

  1. In ChatGPT Work, type @skill-creator and paste your SKILL.md, or describe the task and let it draft one.
  2. Or create the folder with SKILL.md yourself. OpenAI says standalone skills run in the ChatGPT desktop app.
  3. To run a skill, type @ and choose it. ChatGPT may also choose it when your request matches its description.
  4. To use the skill on the web and on mobile, or to share it, package it in a plugin.

OpenAI’s skills page names no plans. Emeri is still confirming which plans can add your own skills, including Plus and Pro.

When not to use AI

  • A task you do once. A skill pays off through repetition.
  • A task where you cannot yet say what a good result looks like. Write that down first, by hand, before you write a spec.
Recall from memoryWhat three things should a skill’s description say, and why does it matter more than the instructions below it?Answer it without looking back, then show the answer

What the task is, when to use it, and what it is not for. The assistant reads only each name and description at first, so the description decides whether the skill runs at all.

Exercise · your project

Write the spec for the task you chose in Lesson 2.

  1. Answer the interview prompt for your task and save the result as SKILL.md.
  2. Run the review prompt on your file and fix each problem it finds.
  3. Dry-run the spec in a new conversation on two weeks of real inputs.
  4. Check that the description says what the skill is not for.
  5. Save the file in a folder with the same name as the skill.

Sources