Skills for Complete Beginners

The Big Picture

You already know how to ask. A skill is how you stop asking the same way twice.

You ask an AI to write a weekly sales recap. It does a decent job. Tomorrow you ask again. You re-explain the format, the tone, what not to invent, who it is for. Next week you forget a constraint and the recap comes back as a novel.

A skill is a recipe the agent reads before it does that job. A short markdown file, usually named SKILL.md. What the job is, when to use it, the steps, the don’ts. You write it once.

Work you repeat — recaps, listing drafts, SOP first passes, research briefs
Taste you do not want to retype — voice, format, “never invent numbers”
Handoffs — the next person (or the next agent) can run the same job

You already know the language. A skill is Markdown. You edit it in Cursor like any other note.

The Cookbook Analogy

A cookbook on the counter→A folder of skills

One recipe card→One SKILL.md file

Dish name and when to cook it→Name + description at the top

Ingredients and steps→What to read, what to write, in order

“Don’t substitute salt for sugar”→The don’ts

Cooking from memory every night→A one-off prompt you retype

A sticky note on the fridge→A rule — standing taste, not a recipe

The oven and the mixer→MCP / APIs — the hands, not the recipe

Key Terms

Skill

A reusable recipe for one job. The agent reads it, then does that job the way you defined.

SKILL.md

The recipe card. Markdown with a short header (name, description) and the steps underneath.

Description

The sentence that tells the agent when to pull this card. A label, not a slogan.

Trigger

You type /weekly-sales-recap, or the agent notices the job matches the description.

What a Skill Looks Like

A skill is a folder with one required file:

folder

weekly-sales-recap/
└── SKILL.md

Two parts: a short header, then the recipe in Markdown.

The file

---

name: weekly-sales-recap

description: 5-bullet recap from last week’s numbers.

---

# Weekly sales recap

1. Read only what I pasted.

2. Five bullets. One decision.

What it means

Weekly sales recap

The agent only uses numbers you gave it. It writes five bullets and either a decision or “none needed.” It does not invent, and it does not write a novel.

The block between --- lines is frontmatter — just a label. Name is the slug: lowercase, hyphens, no spaces. Description is the search label. “Turn last week’s sales numbers into a 5-bullet recap” beats “helps you stay on top of the business.”

Your First Skill

Do this once with a job you already repeat. Do not start by designing a library.

Pick one recurring job

Recap, rewrite, first-draft SOP, competitor scan — something you have asked an agent more than twice.

Create the file

In Cursor, make my-first-skill/SKILL.md. Paste a header. Give it a boring name that matches the job.

Write Do / Don’t

Numbered steps. A short don’t list. If you are scrolling, you packed two jobs into one card.

Run it on real input

Fix the card, not the chat, when it misses.

You do not need a special installer. A markdown file in the project is enough.

When to Write One

Write a skill when all three are true: you will do this job again, you care how it is done, and you are tired of pasting the same paragraph.

Write it

The job repeats. Format, tone, sources, and don’ts matter. You have already prompted it a few times and know what “good” looks like.

Don’t

Still figuring out “good.” Truly one-off. Trying to encode the entire company into one file.

The one-job test. If the description needs the word “and” twice, it is two skills. draft-listing-bullets is good. do-listing-and-ppc-and-inventory is not.

Skills vs Prompts vs Rules

These three get mashed together. They are not the same shelf.

	Prompt	Rule	Skill
Lives	This chat	Settings / a rules file	A `SKILL.md` folder
Lasts	This conversation	Until you change it	Until you change it
Scope	This one ask	Almost every job	One named job
Example	“Rewrite this email shorter”	“No hype. Short sentences.”	“Turn a Loom into an SOP”

Prompt = order off the menu tonight. Rule = house style. Skill = the recipe for a dish you cook every week.

A fourth thing — MCP / APIs — is how the agent gets data or takes an action in another app. Hands, not instructions. A skill can say “use the Gmail tool.” It does not replace the tool.

Where Skills Live

Project skills

In the repo, next to the work. Anyone who clones the project gets the recipe. How this business does the job. GitHub 101.

Personal skills

In your own folder, used across projects. How you like work done, regardless of the repo.

Different apps stash them in slightly different folders (.cursor/skills, .claude/skills, .agents/skills). The shape does not change: a folder, a SKILL.md, a name, a description. If you can see the file, you can edit the recipe.

How the Agent Uses Them

You do not compile a skill. The agent reads the file.

You call it — /weekly-sales-recap or “use the weekly sales recap skill.”
It matches the description — you say “summarize last week’s numbers” and the card fits.
You @ the file — in Cursor, point at SKILL.md like any other file.

Then it follows the steps. If the skill says “read only what I pasted” and you pasted nothing, a good skill tells it to stop and ask — not to invent. You still review the output. A skill makes the job consistent. It does not make you optional.

Daily Loop

Notice a repeat

You just typed the same instructions for the third time.

Freeze the recipe

One SKILL.md. Do / Don’t. One job.

Run it on real work

Not a toy example.

Edit the file when it misses

Not the chat history. Commit it if it belongs to the project.

Vs Other Tools

Tool	What it is	When
Skill	A recipe for one job	The job repeats and you care how
Prompt	A one-off ask	You will not do this again
Rule	Standing taste	Voice, don’ts, always-on prefs
Markdown	The language of the recipe	Markdown 101
Cursor	The workshop	Cursor 101
CLI / API / MCP	How programs talk — the hands	How programs talk

Common Mistakes

Mistake	Better
One giant “company skill”	One job per card
Slogan for a description	Name the job and the output
No don’ts	Write the failure mode
Editing the chat, not the file	Fix `SKILL.md`
Ten skills on day one	One skill you will run this week
Treating a skill as an app	It is a markdown file the agent reads
Secrets in the file	Never paste passwords or API keys

Cheat Sheet

SKILL.md

---
name: job-name
description: What it does, in one sentence, with the output named.
---

# Job name
## Do this
1. …
## Don't
- …

Stop re-explaining → write SKILL.md. Make it fire → put the job in the description. Keep it short → one job, one screen. Fix a bad run → edit the file.

Glossary

Skill = reusable recipe for one agent job. SKILL.md = the file. Frontmatter = the --- block (name, description). Trigger = you call it, or the agent matches the description. Rule = always-on taste, not a recipe. Prompt = a one-off in chat. Project skill = lives in the repo. Personal skill = follows you.