title: "What's the Difference Between a Claude Code Skill and a Prompt?" description: "A Claude Code skill is a stored, versioned, triggerable instruction file. A prompt is typed and forgotten. Here is exactly where each one belongs." pubDate: "2026-04-13" category: skills tags: ["claude-code-skills", "prompts-vs-skills", "foundations"] cluster: 2 cluster_name: "Skills vs Agents vs Prompts" difficulty: beginner source_question: "What's the difference between a Claude Code skill and a prompt?" source_ref: "2.Beginner.1" word_count: 1480 status: draft reviewed: false schema_types: ["Article", "FAQPage"]

What's the Difference Between a Claude Code Skill and a Prompt?

Quick answer: A Claude Code skill is a stored SKILL.md file that lives in your project or user directory, has a named trigger, and runs the same defined process every time. A prompt is text you type into a chat window. A skill persists, is versioned, and is sharable. A prompt disappears when you close the tab and has no trigger.

What Is a Claude Code Skill?

A Claude Code skill is a plain-text markdown file stored in .claude/skills/, containing a named trigger, step-by-step process, output format, and constraints. It runs identically across every Claude Code installation that has the file, with no code, no deployment step, and no API configuration required. When you type /commit or /review-pr, Claude reads that file and executes accordingly — the same way, every time.

The file format is plain text. No code required, no deployment step, no API configuration. Every Claude Code installation that has the file will behave identically on the same trigger.

A working skill has all four of the following components:

  • A name — the trigger phrase or slash command
  • A description under 1,024 characters
  • A process that Claude can follow without interpretation
  • An output contract that specifies what "done" looks like

A skill missing any of these four components is not a production skill. It is a draft with a .md extension. In practice, the missing output contract is the most common failure point — the process exists, but the expected output is never defined.

For a detailed walkthrough of every section of a skill file, see What Goes in a SKILL.md File?.

What Is a Prompt?

A prompt is text you type into a chat session — it instructs Claude once, for that conversation only, then disappears. There is no storage location, no trigger name, no version history, and no enforced output format. It works well for one-off tasks but cannot replicate consistently across team members or sessions.

That definition sounds reductive — but it accurately describes most instructions people use with Claude. A message like "review this code for security issues and summarize the findings" is a prompt. A /security-review skill that runs the same review process, formatted identically, every time you invoke it is something fundamentally different. The distinction matters because missing these properties is precisely what causes workflow failures at scale.

Prompts work well for:

  • One-off questions with no expected reuse
  • Exploratory work where the output shape is still unknown
  • Personal tasks where consistency across sessions is not the goal

They fail at:

  • Anything a second developer on your team needs to run the same way
  • Any process where output format consistency matters
  • Any task where you have improved the instructions and want the improvement to propagate

Why Does the Difference Matter?

The gap between a prompt and a skill compounds with every team member you add and every week you run the same process. A prompt holds one person's refinement in their head; a skill stores it in a file that everyone installs, versioned in Git, with the full change history reviewable before it ships.

A prompt is personal. You refined it over six weeks. You know to add "be specific about line numbers" at the end. Your colleague does not. They run their version, get different output, and have no way to know why.

"Skills have quickly become one of the most popular extension points in Claude Code. They're flexible, easy to create, and simple to share." — Tort Mario, Engineer, Anthropic (April 2026, https://medium.com/@tort_mario/skills-for-claude-code-the-ultimate-guide-from-an-anthropic-engineer-bcd66faaa2d6)

A skill is shared. Your six weeks of refinement live in one file. Every team member who installs it gets your best version. When you improve the process, one file update propagates to every user on their next pull. The improvement does not need to be re-communicated.

The version control difference is concrete. A prompt stored in a Notion doc has no history, nobody knows which version produced which output. A skill stored in a Git repository carries a full audit trail. Every change is attributable, reversible, and reviewable before it ships to the team.

The trigger difference matters for workflow integration too. A prompt requires you to remember to include it. Each use requires you to:

  1. Open the chat
  2. Reconstruct the context
  3. Type the instructions
  4. Run the task

A skill is invoked by name. You type /review-pr, and the full process fires exactly as defined.

Most AI skills in community libraries are prompts in a trenchcoat: saved to a file but without the trigger, output contract, or process structure that makes a skill deployable. That is why community skill reliability varies as much as it does.

In AEM's production skill builds, we've found that the single most common reason a skill fails in team use is a missing output contract — the process exists, but nobody defined what "done" looks like, so every user interprets the output differently.

When Should You Use a Prompt vs a Skill?

Use a prompt when you are exploring a problem for the first time and the output shape is still unknown, or when the task is genuinely once-off. Use a skill as soon as you have run the same prompt more than twice — by the third run, you have already paid the cost of building a skill in repeated typing and inconsistency.

Use a prompt when:

  • You are exploring a problem for the first time and do not yet know the output shape
  • The task is genuinely one-off and you will not run it again
  • The instructions are short enough that typing them takes less time than building a skill

Use a skill when:

  • You have run the same prompt more than twice
  • The output format needs to be consistent across runs or across team members
  • You have refined the instructions and want the refinement to persist
  • Another person needs to run the same process without asking you how

The threshold is lower than most people assume. Three runs is enough. At the third run, you have already paid the cost of a skill in repeated typing and inconsistency. Build the skill and stop paying it.

How Do You Turn an Existing Prompt into a Skill?

Converting an existing prompt to a skill takes four steps and roughly 20 minutes for a typical workflow. You define the trigger, extract and structure the instructions as numbered steps, write an output contract, and add the YAML frontmatter header. The file is then installed by placing it in .claude/skills/.

Four steps cover most conversions:

  1. Define the trigger. What slash command or invocation phrase triggers this process? /commit, /review, /release-notes. One command, one skill.

  2. Extract the instructions. Take your best prompt version and structure it as numbered steps. Each step should be a specific instruction Claude can execute without interpretation. Remove hedges. "Make it concise" becomes "Output the summary in 3 bullet points, each under 15 words."

  3. Write the output contract. Define what the output looks like: format, sections, length constraints, any required fields. If you cannot describe the output clearly, the skill is not ready to be built.

  4. Add the frontmatter. Create the YAML header with name, description, and any other relevant fields. Keep the description under 1,024 characters. This is the metadata Claude uses for discovery.

Save the file to .claude/skills/ in your project directory. The skill is installed.

The full process for building a first skill from scratch is in How Do I Create My First Claude Code Skill?.

For a broader look at where skills fit alongside agents, CLAUDE.md, and other Claude Code tools, see Claude Code Skills vs Agents vs Prompts: When to Use Which.

FAQ

What's the simplest possible Claude Code skill I can build in 5 minutes?

A commit message skill is a reliable starting point. Create a file at .claude/skills/commit.md with a name: commit field, a description explaining it generates commit messages from diffs, and a 3-step process: read the staged diff, generate a message in the conventional commits format, and print it for review. That is a deployable skill in under 20 lines.

Can I use Claude Code skills without a paid subscription?

Skills work in any Claude Code installation. Whether a particular installation requires a paid subscription depends on the Claude Code tier you are using, not the skill format. The SKILL.md file format has no subscription dependency. Check your Claude Code plan documentation for access details.

Do Claude Code skills work in VS Code or only in the terminal?

Claude Code skills work wherever Claude Code runs: the terminal, the VS Code extension, JetBrains IDEs, and other supported editors. The skill file is read by the Claude Code process, not by the editor. Any editor with Claude Code installed and configured will trigger skills by name.

How do Claude Code skills compare to GitHub Copilot custom instructions?

Copilot custom instructions in copilot-instructions.md are always-on context applied to all Copilot sessions in a repository. They are closer to Claude's CLAUDE.md than to a skill. Claude Code skills are on-demand, named, triggered processes. The two serve different purposes. SKILL.md files port to 14+ platforms including Cursor and Gemini CLI. Copilot instruction files are specific to Copilot and do not transfer.

Should I use a Claude Code skill or a custom GPT for my workflow?

Use a Claude Code skill if your work happens in Claude Code or a compatible coding tool. Custom GPTs are locked to the ChatGPT interface and do not transfer to Claude Code, Cursor, or other platforms. If your workflow is not dependent on ChatGPT specifically, skills are the more portable and version-controllable choice.

Last updated: 2026-04-13