AI skills: how SKILL.md files make complex work repeatable

Most people use AI like a talented intern with amnesia. You explain the job. You get a decent draft. Next week you explain the job again, slightly differently, and the draft comes back a different shape. Prompt tricks help for a day. They do not survive a multi-step analysis, a team of three, or a Friday afternoon.

Skills fix that. A skill is a small folder with a SKILL.md file — a named playbook the model can load when the work matches. Claude and ChatGPT both now use this pattern (it is becoming an open standard). You write the name, the description of when to use it, and the steps. The model stops improvising the method and starts executing yours.

Do not hand-author a skill from a blank page. Describe the process in plain English, have AI draft the SKILL.md, then you review.

What a skill actually is

At minimum, a skill is a directory named for the job, containing one file: SKILL.md. That file has two parts. YAML frontmatter at the top (name and description). Markdown instructions below (the steps, the output format, the checks). Optional extras live beside it: a references folder for long examples, scripts if a step must be exact, templates the model should copy.

Both Anthropic and OpenAI load skills in layers. At the start of a chat, the model only sees each skill’s name and description — just enough to decide “this job matches.” Only then does it read the full SKILL.md. That is why the description matters more than the prose you are proud of: if the when is vague, the skill never fires.

---
name: weekly-competitor-digest
description: Compiles a Thursday digest of competitor moves, pricing, and launches. Use when the user asks for competitive intel, a market scan, or a weekly rival update.
---

# Weekly competitor digest

## Inputs
Named competitors, markets, and sources to trust.

## Steps
1. Scan only the named sources.
2. List up to 20 items. Each item: what changed, why it matters, confidence.
3. Flag rumors separately from confirmed launches.
4. End with three questions a human should still answer.

## Output
Markdown. No invented products. If a fact is missing, say so.

What Claude and ChatGPT both recommend

Anthropic’s skill-authoring guidance is blunt: assume the model is already smart. Do not spend tokens explaining what a PDF is. Keep SKILL.md lean (they suggest staying under about 500 lines). Put the rare, heavy reference material in sidecar files the model opens only if needed. Write the description in the third person, and include both what the skill does and when to use it. Name skills clearly (analyzing-spreadsheets, not helper). Test the skill against the models you actually use.

OpenAI’s guidance rhymes. Keep each skill focused on one job. Prefer written steps over scripts unless you need a calculation that must not drift. Write imperative instructions with explicit inputs and outputs. Front-load trigger words in the description so implicit matching still works if the host shortens it. Then test real prompts: would this sentence actually pull the skill in? ChatGPT’s own academy advice is to start a chat with “Build me a skill…” and include the job, the inputs, numbered steps, the output format, and final quality checks.

The shared rule: a skill is a procedure, not an essay about your industry.

Let AI write the file. You review it.

The fastest way to a good skill is not sitting in a text editor inventing YAML. Talk through the work the way you would brief a colleague, then ask the model to produce the folder.

• In Claude: describe the workflow and ask it to draft a skill (Claude Code can write the folder; on claude.ai you can add custom skills in settings). Invoke with /skill-name in Claude Code, or let the description trigger it.
• In ChatGPT: say “Build me a skill…” or, in ChatGPT Work, invoke @skill-creator. In Codex, use $skill-creator. ChatGPT can also draft a skill from a recorded walkthrough (Record & Replay) if showing is easier than explaining.
• Tell it the job-to-be-done, required inputs, numbered steps, required output shape, and the last checks before it is “done.”
• Ask for a specific description: what it does, when to use it, and when not to.
• Read the draft the way you would read a junior’s SOP. Cut fluff. Add the one constraint you would be angry to forget (client names stay out; never invent a number; always cite the source).
• Install it, run three real prompts that should trigger it, and one that should not. Fix the description first if it misfires.

You still own the process. AI is a fast clerk for the file format. If the skill is wrong, the model will repeat the wrongness with great confidence — which is why review is the job, not typing the markdown by hand.

With skill vs without skill

This is the difference that shows up after the second week, when you are no longer in the mood to re-explain yourself.

Set them up in Claude

A custom skill is a folder. The directory name should match the name field in the file. Personal skills live in ~/.claude/skills/ (available everywhere). Project skills live in .claude/skills/ inside a repo (shared with the team). Put SKILL.md at the root of that folder. On claude.ai, add custom skills in settings; in Claude Code they are picked up from those folders.

Two ways to run one. Ask in ordinary language that matches the description (“make the Thursday competitor digest”). Or invoke it directly with /skill-name. If it does not fire, the description is usually the bug — not the steps.

Set them up in ChatGPT

ChatGPT and Codex use the same SKILL.md shape. Create with @skill-creator (ChatGPT Work) or $skill-creator (Codex), or upload a skill folder. In ChatGPT, type @ to pick a skill. In Codex, /skills or $skill-name. Implicit use still depends on that description. Codex looks in .agents/skills in the project, and in ~/.agents/skills for your personal library. Keep one job per skill; if you need to share a bundle, OpenAI wants that packaged as a plugin.

Build a library, not a pile of chats

Start with the jobs you already repeat. A skill is worth making when you have done the work twice and resented explaining it the second time.

• Weekly or monthly competitive / vendor / pricing scans
• Client-ready summaries from a folder of notes or PDFs
• Proposal or engagement-letter first drafts in your voice
• Meeting-to-action conversions with a fixed output shape
• Spreadsheet or report analysis with the same checks every time
• Content in house style (blog, LinkedIn, newsletter) with a last-pass list
• Research memos: sources, claims, confidence, what is still unknown
• Onboarding a teammate: “how we use AI here” as a skill they invoke

Name them so a tired human can find them. Keep a simple index — even a note with skill name, when to use it, and how to invoke it. Personal library first. Promote a skill into the project or the team folder only after you have run it on real work and edited the sharp edges.

Invoke on purpose at first: /weekly-competitor-digest, @weekly-competitor-digest, or “Use the weekly-competitor-digest skill on this.” Once the description is tight, you can let auto-matching take more of the load. Never put secrets in a skill file. Never let a skill skip the human last pass on anything that leaves the building.

A library of skills is how a practice compounds. The model gets new. The playbook stays yours.

If you want help turning one messy recurring job into a reviewed skill — and then a small library — book a complimentary Discovery Call. Bring the task you already do twice. We will talk through the brief, the SKILL.md, and how you and your team should invoke it.