Agent Skills 102: Skills

What is a skill?

A skill teaches the agent a task you do again and again, so it is done the same way every time. Instead of re-explaining a process in every session, you write it down once and the agent follows it.

Think of it as a recipe card for your agent.

Each skill is a short file called SKILL.md, in its own folder, with two parts:

A name and a one-line description of when to use it.
The steps to follow.

Claude Code and Antigravity both understand this format, so one skill works in either tool.

How it works

At the start of every session, the agent reads only the name and description of each skill it has. It reads the steps only when it needs them. That keeps skills cheap: you can have many without filling up the conversation.

The agent uses a skill in two ways:

You ask for it by name. “Use the render-check skill.” In Claude Code you can also type /render-check.
The agent picks it on its own when your request matches the description. That is why a good description says when to use the skill, not only what it does.

What a skill looks like

---
name: render-check
description: Render the Quarto book and fix any errors. Use after editing chapters or _quarto.yml, or when asked to check that the book builds.
---

1. Run `quarto render` in the project root
2. Check the output for errors or warnings
3. If there are errors, read the error message and fix the issue
4. Re-render until it builds cleanly
5. Report what you fixed (if anything)

The part between the --- lines is the name and description. Everything below is the steps.

Make one with a prompt

As with your instructions file in Skills 100, you do not need to know where skills go. Ask the agent:

Copy-paste this prompt into your agent

Create a skill for this project named render-check, in the folder where you load skills for this project, so it is committed with the repo. Tell me the path you used.

Description: Render the Quarto book and fix any errors. Use after editing chapters or _quarto.yml, or when asked to check that the book builds.

Steps:

Run quarto render in the project root

Check the output for errors or warnings

If there are errors, read the error message and fix the issue

Re-render until it builds cleanly

Report what you fixed (if anything)

Skills are loaded when a session starts, so /clear or restart the agent before you try it:

Use the render-check skill.

Change the name, description and steps for your own task. You can also ask the agent to turn something you just did together into a skill: “Make a skill from the steps we just followed to clean up the bibliography.”

More examples

format-bib

---
name: format-bib
description: Clean up the bibliography file. Use when asked to tidy, check or sort references.bib.
---

1. Read `content/references.bib`
2. Check each entry for:
   - Missing fields (author, title, year, journal/publisher)
   - Inconsistent formatting (e.g., mixed use of curly braces)
   - Duplicate entries (same DOI or matching author+title+year)
3. Fix any issues found
4. Sort entries alphabetically by citation key

new-chapter

---
name: new-chapter
description: Add a new chapter to the Quarto book. Use when asked to add, create or start a chapter.
---

1. Ask me for the chapter title and which part of the book it belongs in
2. Create `content/<short-name>.qmd` with a `title:` in its front matter
3. Add it to `book.chapters` in `_quarto.yml`, in the right part
4. Run `quarto render` and fix any errors
5. Tell me the file name and where it appears in the book

Tips for writing skills

Write the description for the agent. Say when to use the skill, with the words you would actually use to ask for it.
Be specific. “Check for problems” is vague. “Run quarto render and check for errors” is actionable.
Use numbered steps. The agent follows them in order.
Include the actual commands. Don’t make the agent guess what to run.
Keep them short. A skill that’s a full page long is probably two skills.

Project skills and personal skills

Like instructions, skills can belong to one project or to you:

Project skills are committed with the repo. Anyone who clones it, and any agent working in it, gets them. Good for tasks tied to that project, like render-check.
Personal skills live in your home directory and work in every project. Good for your own habits. Ask the agent for “a personal skill” instead of “a skill for this project”.

Skills vs. instructions

	Instructions (`CLAUDE.md` or `AGENTS.md`)	Skills
Purpose	Context and conventions	Reusable task recipes
When it’s read	All of it, at every session start	Name and description at start; steps only when used
Contents	Build commands, architecture, your workflow phrases	Step-by-step procedures

Instructions give the agent background it always needs. Skills give it procedures to follow on demand. If your instructions file is getting long with step-by-step procedures, move them into skills.