Should you use a skill or a prompt?
Use a prompt when you are asking for something once or steering by hand. Use an Agent Skill when you want the agent to know a procedure and apply it on its own, every time it fits. A good reusable prompt with blanks covers most one-person, run-it-yourself tasks. A skill earns its setup when the same instructions keep coming back, when the agent should apply them without being told, or when the job needs scripts and reference files.
Anthropic's Agent Skills overview draws the line like this: "Unlike prompts (conversation-level instructions for one-off tasks), Skills load on demand, so you don't have to repeat the same guidance across conversations."
What is the difference between a prompt and a skill?
A prompt is the text you send. It lives in your message, it applies to that conversation, and it works in any chat tool with any model. A reusable prompt is the same thing saved for later, usually with blanks such as {{language}} or {{tone:friendly}} that you fill in before sending. You decide when to use it.
A skill is a folder with a SKILL.md file: YAML frontmatter with a name and a description, then Markdown instructions, plus optional scripts and reference files. The agent sees the name and description at all times and loads the rest when your request matches. The agent decides when to use it, and you can also call it by name.
Anthropic's Skills explained post sums up what each provides in two phrases: prompts give "Moment-to-moment instructions"; skills give "Procedural knowledge."
Skills vs prompts side by side
| Reusable prompt | Agent Skill | |
|---|---|---|
| What it is | Text you paste or send | A folder with SKILL.md, scripts and references |
| Who starts it | You, every time | The agent when the description matches, or you by name |
| Lasts for | One conversation | Every conversation where the skill is installed |
| Variables | Blanks you fill in, like {{name}} |
Arguments after the command in Claude Code, like $ARGUMENTS |
| Context cost | The whole prompt, every time you send it | About 100 tokens idle; full text only when triggered |
| Can run code | No, it can only ask the model to | Yes, bundled scripts run and only their output enters context |
| Works where | Any chat app or model | Agents that support skills, such as Claude, Codex and Cursor |
| Setup | None | A folder with valid frontmatter, installed per tool |
| Sharing | Copy and paste | Commit the folder or install it from a repo |
| Main risk | Low; you read every word you send | A skill from someone else can carry hidden instructions or scripts |
When is a reusable prompt enough?
Keep it as a prompt when any of these is true:
- You change it every time. If the core of the request shifts each run, a template with blanks is the right shape. Skills work best when the procedure is stable.
- You trigger it on purpose. Drafting a cold email, rewriting a paragraph, brainstorming names: you know when you want these, so automatic loading adds nothing.
- You use it in many tools. A prompt pastes into ChatGPT, Claude, Gemini, Cursor or anything else. Skills need an agent that supports them, and each tool installs them separately.
- It's short. A few lines of instruction cost little to send, and a skill around them is mostly ceremony.
- You're still finding the wording. Iterate on a prompt until it reliably works, then decide whether it deserves a skill.
Our prompt templates page has examples of the kind of reusable prompt that should stay a prompt.
When should you make an Agent Skill?
Make a skill when the instructions describe how your work gets done, not a single request:
- You keep pasting the same block. Your commit message format, your PR checklist, your house style for release notes. Anthropic's blog post gives a matching signal for Projects: "If you find yourself copying the same instructions across multiple Projects, that's a signal to create a skill instead."
- The agent should apply it without being asked. A skill whose description says "use when writing a database migration" gets picked up when you ask for a migration, even if you forgot it existed.
- It needs files. A schema, a style guide, a template or a validation script can sit in the skill folder. The overview notes that bundled files "don't consume context until accessed."
- It needs to be exact. A script the skill runs gives the same result every time. The overview explains that when a skill runs a script, "the script's code never loads into the context window," only its output does.
- A team should share it. A skill folder in a Git repo is reviewable like code, and everyone's agent gets the same procedure.
What does each cost in context?
A prompt costs its full length every time you send it. A 2,000-token prompt pasted into ten conversations is 2,000 tokens in each.
Skills load in stages. The overview's table gives the numbers:
| Level | When loaded | Token cost |
|---|---|---|
| Metadata (name and description) | Always, at startup | About 100 tokens per skill |
Instructions (SKILL.md body) |
When the skill is triggered | Under 5k tokens |
| Resources and scripts | As needed | None until accessed |
That is why a library of dozens of installed skills stays cheap, while a library of long prompts you paste in "just in case" does not.
How do you turn a prompt into a skill?
Start from a prompt that already works. Here is a reusable prompt with blanks:
Write release notes for version {{version}} of {{product}}.
Group changes under New, Improved and Fixed. One line per change,
written for {{audience:end users}}. Skip internal refactors.
Commits:
{{commits}}
The same procedure as a skill moves the stable part into instructions and leaves the variable part to the conversation:
---
name: release-notes
description: Write release notes from a list of commits or merged PRs, grouped
under New, Improved and Fixed. Use when the user asks for release notes,
a changelog entry or a summary of what shipped in a version.
---
# Release notes
1. Ask for the version number and commit list if they are missing.
2. Group changes under New, Improved and Fixed.
3. Write one line per change for end users unless told otherwise.
4. Skip internal refactors, dependency bumps and test-only changes.
5. Follow the format in template.md.
Three things changed. The description now says what the skill does and when to use it, which is what the agent matches against. The overview requires both. The blanks became steps that ask for missing input. And the format moved into a reference file that loads only when needed.
Keep the frontmatter valid: per Anthropic's rules, name is at most 64 characters of lowercase letters, numbers and hyphens, and description is at most 1,024 characters. The free SKILL.md generator does this conversion in your browser and checks both limits. For the full format, see how to write a SKILL.md.
Where do skills work, and what should you watch for?
Claude Code reads skills from ~/.claude/skills/ and .claude/skills/. In the Claude apps, you upload a skill as a ZIP under Customize, Skills, and the help center notes the feature "requires code execution to be enabled." The API takes skills through its Skills endpoints. The overview says custom skills don't sync between claude.ai and the API, so upload them to each. Claude Code is the exception in one direction: per the Claude Code skills docs, when you sign in with your claude.ai account it downloads the skills enabled there, but it never uploads its own. Codex, Cursor and other agents read the same Agent Skills format from their own folders.
Treat skills from others like software. Anthropic's advice is to "Use Skills only from trusted sources," and to read every bundled file before you turn one on. A prompt has no such risk: what you paste is all there is.
Which should you pick?
- One-off or changes every time: a prompt.
- You trigger it, the wording is stable, and you use several AI tools: a saved prompt with blanks.
- The agent should apply it unprompted, or you keep pasting it: a skill.
- It needs scripts, templates or reference files: a skill.
- A team should follow it the same way: a skill in a shared repo.
Many people keep both: a prompt library for asking, and a smaller set of skills for the procedures that have settled down.
Where Kipt fits
Kipt keeps both kinds in one place. Prompts with {{name}} or {{name:default}} blanks and Agent Skills live as Markdown in a private GitHub repo you own, searchable with Cmd+K. You can import skills from a GitHub link, a folder or a .zip, and install every skill into Claude Code or Codex with one command: npx skills add https://github.com/<you>/<repo>.git --all -g.