# Skills for Complete Beginners A practical guide to agent skills — written for someone who has never written a `SKILL.md` and does not want to become a developer. --- ## Table of Contents 1. [The Big Picture](#the-big-picture) 2. [Key Terms (Plain English)](#key-terms-plain-english) 3. [What a Skill Looks Like](#what-a-skill-looks-like) 4. [Your First Skill](#your-first-skill) 5. [When to Write One](#when-to-write-one) 6. [Skills vs. Prompts vs. Rules](#skills-vs-prompts-vs-rules) 7. [Where Skills Live](#where-skills-live) 8. [How the Agent Uses Them](#how-the-agent-uses-them) 9. [A Simple Daily Loop](#a-simple-daily-loop) 10. [Skills vs. Other Tools](#skills-vs-other-tools) 11. [Common Mistakes and How to Avoid Them](#common-mistakes-and-how-to-avoid-them) 12. [Quick Reference Cheat Sheet](#quick-reference-cheat-sheet) 13. [Glossary](#glossary) --- ## The Big Picture ### What problem does a skill solve? 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 — so you stop re-explaining it. It is a short markdown file, usually named `SKILL.md`, sitting in a folder. The file says: what this job is, when to use it, the steps, and the don'ts. You write it once. The agent follows it whenever that job comes up. It is designed for: - **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](https://goaspi.com/101/markdown/). You can edit it in [Cursor](https://goaspi.com/101/cursor/) like any other note. ### The cookbook analogy | Real world | Skill equivalent | |---|---| | A cookbook on the counter | A folder of skills | | One recipe card | One `SKILL.md` file | | The dish name and when to cook it | The 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 ([CLI, API & MCP](https://goaspi.com/101/how-programs-talk/)) | ### What makes a skill different 1. **It is a file you own.** Not a setting buried in a chat product. You can copy it, edit it, put it in GitHub. 2. **It is one job.** “Weekly sales recap” is a skill. “Run my company” is not. 3. **It is portable.** The same `SKILL.md` shape works in Cursor, Claude Code, Codex, Gemini, and other agents that read the format. 4. **It does not run by itself.** A skill is instructions. Something still has to *do* the work — you, or an agent you asked. 5. **It is not magic.** A vague skill gets vague work. A tight skill gets tight work. --- ## Key Terms (Plain English) ### Skill A reusable recipe for one job. The agent reads it, then does that job the way you defined. ### SKILL.md The recipe card. A markdown file with a short header (name, description) and the steps underneath. ### Description The sentence at the top that tells the agent *when* to pull this card. Write it like a label on a folder, not a slogan. ### Trigger How the skill starts: you type `/weekly-sales-recap`, or the agent notices the job matches the description and offers it. ### Rule Standing taste that applies across jobs — “don’t open a PR,” “write like an operator.” Not a recipe. See [Cursor 101](https://goaspi.com/101/cursor/). ### Prompt A one-off instruction in the chat. Fine for a job you will never do again. ### Bundle / folder The skill is a folder, not a lone paragraph in a chat. `SKILL.md` is required. Extra files (examples, checklists) are optional. --- ## What a Skill Looks Like A skill is a folder with one required file: ``` weekly-sales-recap/ └── SKILL.md ``` The file has two parts: a short header, then the recipe in Markdown. ```markdown --- name: weekly-sales-recap description: Turn last week's sales numbers into a 5-bullet recap for the owner. --- # Weekly sales recap ## Do this 1. Read only the numbers I pasted or attached. 2. Write exactly 5 bullets: what moved, why it matters, what to watch. 3. End with one decision, or “no decision needed.” ## Don't - Invent numbers or fill gaps with guesses - Write a narrative - Recommend spend changes ``` The block between `---` lines is called **frontmatter**. It is just a label: the name of the recipe and when to use it. Everything under that is the instructions — same Markdown you already use for notes. **Name** = the slug. Lowercase, hyphens, no spaces: `weekly-sales-recap`. **Description** = the search label. Put the *job* in it, not the philosophy. “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. 1. Pick **one** recurring job. Recap, rewrite, first-draft SOP, competitor scan — something you have asked an agent more than twice. 2. Open a folder in [Cursor](https://goaspi.com/101/cursor/). Create `my-first-skill/SKILL.md`. 3. Paste the header. Give it a boring name that matches the job. 4. Write **Do this** as numbered steps. Write **Don't** as a short list. 5. Run it on real input. Fix the card, not the chat, when it misses. A good first skill fits on one screen. If you are scrolling, you packed two jobs into one card. Split it. You do not need a special installer for a first skill. A markdown file in the project is enough. Many agents also look in a `skills/` folder next to your other project files. --- ## When to Write One Write a skill when **all three** are true: 1. You will do this job again. 2. You care how it is done (format, tone, sources, don'ts). 3. You are tired of pasting the same paragraph. Do **not** write a skill when: - You are still figuring out what “good” looks like — prompt it a few times first, then freeze the recipe - The job is truly one-off - You are trying to encode your entire operating system into one file ### The one-job test If the description needs the word “and” twice, it is two skills. - Good: `draft-listing-bullets` - Good: `pull-review-themes` - Bad: `do-listing-and-ppc-and-inventory` --- ## Skills vs. Prompts vs. Rules These three get mashed together. They are not the same shelf. | | Prompt | Rule | Skill | |---|---|---|---| | **Lives** | In this chat | In settings / a rules file | In 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. Always-on. - **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. That is hands, not instructions. See [CLI, API & MCP](https://goaspi.com/101/how-programs-talk/). A skill can *say* “use the Gmail tool” or “read the file I attached.” It does not replace the tool. --- ## Where Skills Live Two common homes: **Project skills** — in the repo, next to the work. Example: `skills/weekly-sales-recap/SKILL.md`. Anyone who clones the project (see [GitHub 101](https://goaspi.com/101/github/)) gets the recipe. Use these for how *this* business does the job. **Personal skills** — in your own folder, used across projects. Use these for how *you* like work done, regardless of the repo. Same file shape in both. If two skills share a name, the project one should win for that project — the local cookbook beats the one at home. Different apps stash them in slightly different folders (`.cursor/skills`, `.claude/skills`, `.agents/skills`). The important part 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. You do not “install an app.” The agent **reads the file**. Typical paths: 1. **You call it.** `/weekly-sales-recap` or “use the weekly sales recap skill.” 2. **It matches the description.** You say “summarize last week’s numbers for me” and the agent pulls that card because the description fits. 3. **You @ the file.** In Cursor, point at `SKILL.md` the same way you @ 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. --- ## A Simple Daily Loop 1. **Notice a repeat.** You just typed the same instructions for the third time. 2. **Freeze the recipe.** One `SKILL.md`. Do / Don't. One job. 3. **Run it on real work.** Not a toy example. 4. **Edit the file** when it misses — not the chat history. 5. **Commit it** if it belongs to the project. [GitHub 101](https://goaspi.com/101/github/). That is the whole compounding loop. Skills you never edit are skills you never actually used. --- ## Skills vs. Other Tools | Tool | What it is | When to use it | |---|---|---| | **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 the recipe is written in | [Markdown 101](https://goaspi.com/101/markdown/) | | **Cursor** | The workshop where you edit the file | [Cursor 101](https://goaspi.com/101/cursor/) | | **Obsidian** | Your notes and thinking | Linked knowledge, not an agent recipe | | **Buzz** | A shared room with agents | Team context — the skill can still live in the repo | | **CLI / API / MCP** | How programs talk and how agents get hands | [How programs talk](https://goaspi.com/101/how-programs-talk/) | --- ## Common Mistakes and How to Avoid Them | Mistake | What happens | Better | |---|---|---| | One giant “company skill” | The agent ignores half of it | One job per card | | Slogan for a description | It never gets triggered | Name the job and the output | | No don'ts | It invents, hypes, or overreaches | Write the failure mode | | Editing the chat, not the file | Next run makes the same miss | Fix `SKILL.md` | | Ten skills on day one | None of them get used | One skill you will run this week | | Treating a skill as an app | Waiting for a button that does not exist | It is a markdown file the agent reads | | Packing secrets into the file | Keys end up in GitHub | Point at tools / files; never paste passwords | --- ## Quick Reference Cheat Sheet ``` weekly-sales-recap/ └── SKILL.md ← the only required file ``` ```markdown --- name: job-name description: What it does, in one sentence, with the output named. --- # Job name ## Do this 1. … ## Don't - … ``` | I want to… | Do this | |---|---| | Stop re-explaining a job | Write a `SKILL.md` | | Make it fire at the right time | Put the job in the **description** | | Keep it short | One job. One screen. | | Fix a bad run | Edit the file, then run again | | Share it with the team | Put it in the project, commit it | | Write the file | [Markdown 101](https://goaspi.com/101/markdown/) | | Edit it with an agent | [Cursor 101](https://goaspi.com/101/cursor/) | | Understand the “hands” | [CLI, API & MCP](https://goaspi.com/101/how-programs-talk/) | --- ## Glossary | Term | Definition | |---|---| | **Skill** | A reusable recipe for one agent job | | **SKILL.md** | The markdown file that holds the recipe | | **Frontmatter** | The `---` block at the top (name, description) | | **Description** | The label the agent uses to decide when to pull this card | | **Trigger** | You call it, or the agent matches the description | | **Rule** | Always-on taste, not a recipe | | **Prompt** | A one-off instruction in chat | | **Project skill** | Lives in the repo; travels with the work | | **Personal skill** | Lives in your folder; follows you across projects | | **Bundle** | The skill folder — `SKILL.md` plus any extra files | --- Write one recipe for a job you already do. Run it on real input. Edit the card when it misses. More Aspi 101: [Markdown](https://goaspi.com/101/markdown/) · [Cursor](https://goaspi.com/101/cursor/) · [HTML](https://goaspi.com/101/html/) · [CLI, API & MCP](https://goaspi.com/101/how-programs-talk/) · [All 101 Guides](https://goaspi.com/101/).