A Skill is a laminated card

There is a laminated card on the factory floor. It does not explain the philosophy of the assembly process. It says: Step 1. Step 2. If this condition holds, do this instead. Step 3. Check this criterion before moving on. A new worker picks up the card and executes the procedure correctly the first time. The card is not documentation — it is executable instruction.

A "Skill" (the Claude artifact) works the same way. A Skill file is a markdown document that Claude reads at invocation time and acts on — not documentation Claude might reference, but instructions Claude executes.

Why the distinction matters before you write one

If you think of a Skill as documentation, you write it at the wrong level of abstraction. Documentation explains what something does and why. A Skill specifies what to do, in what order, what to check at each step, and what to do when the expected condition does not hold. The specificity is the point.

Here is a documentation sentence: "Pull requests should be reviewed for correctness, style, and security."

Here is a Skill step: "Run git diff main -- '*.py' and list every function whose signature changed. For each changed signature, check whether the corresponding test file in tests/ was also modified. If not, flag it."

The documentation sentence gives Claude a disposition. The Skill step gives Claude an action with an observable completion state. Claude can execute a Skill step. Claude can only approximate a documentation sentence.

How a Skill differs from a system prompt

A system prompt lives in Project settings. It is always active for every conversation in that Project, in the background, before your first message. It shapes Claude's general behavior in that context.

A Skill lives in a .md file — on disk, in a repository, or in a registry. It has these properties a system prompt does not:

• It must be invoked explicitly when the task starts. Claude does not run it automatically.
• It is portable across Projects and across agents. The same Skill file can be installed in any Claude Desktop session, used by any agent that has access to the file.
• It carries a version field in its frontmatter. When the procedure changes, the version increments, and teammates who installed the prior version can see that an update is available.
• It is composable. A Project can invoke multiple Skills. A Skill can reference another Skill.

Think of the system prompt as the standing orders that define the role. Think of a Skill as the procedure card for a specific task within that role. The system prompt says "you are a code reviewer." The Skill says "here is how to execute a security audit of an authentication change."

The sensitive period for writing Skills

There is a moment when a Skill writes itself easily, and you will miss it if you are not watching for it. The moment is: right after you have done a task manually that you expect to do again, while the steps are still fresh, while you can still feel the places where you made a judgment call. That judgment call — the moment where you thought "hmm, it depends on whether X" — is the gotchas section of the Skill. It belongs in the file, not in your head.

If you wait until you have done the task five more times, you will have internalized the procedure and will struggle to articulate the steps explicitly. Write the Skill immediately after the first time you do a task you expect to repeat.

What a Skill file looks like before you open it

A Skill file in a repository looks like this on disk:

# skills/draft-pr-description.md
---
name: draft-pr-description
description: Draft a pull request description from a git diff and a ticket reference
author: Seth Shoultes
version: 1.0.0
---

## Procedure
1. Run `git diff main` and identify the files changed.
...

## Gotchas
- If the diff exceeds 400 lines, ask which files are load-bearing before summarizing.
...

You do not need the Claude UI to read or edit this. It is a text file. You can version it, diff it, review it in a PR, and roll it back. This is what makes Skills shareable in a way that system prompts are not.

If you get stuck

You wrote a Skill and Claude keeps asking clarifying questions when it runs. Every clarifying question is a missing step or an implicit assumption you have not made explicit. After each clarifying question Claude asks, add a step or a gotcha that resolves it. The Skill is done when Claude runs it start-to-finish without stopping.

You wrote a Skill and the output is inconsistent across runs. The procedure has a step with no observable completion state — something like "understand the context" or "review the approach." Replace it with a step that has a concrete action and a concrete check. "Inconsistency" in a Skill is always a procedure problem, not a Claude capability problem.

Deliverable

Before the next lesson: pick one task you do at least twice a month. Write the steps as if you were explaining them to a competent colleague who has never done this exact task but who is not new to the domain. That write-up is the procedure section of your first Skill.