You're building with AI. You've heard about prompts. You've heard about agents. Now everyone's talking about skills. Claude Code has .claude/skills/. Cursor has similar concepts. Every AI coding tool is adopting some version of the pattern.

But what actually is a skill? How is it different from a prompt? Where does an agent fit? And which one should you use for your specific problem?

This article cuts through the confusion. No marketing fluff, no hand-waving — just clear definitions, concrete examples, and a decision framework for choosing the right tool.

A prompt is a natural language instruction sent to an AI model. It can be a question, a command, or a description of what you want.

Write a function that validates email addresses using regex.

That's a prompt. It's immediate, one-shot, and context-dependent. The model reads it, generates a response, and the interaction is complete.

Characteristics of prompts:

• Stateless — no memory between invocations

• Unstructured — free-form text

• Single-turn or multi-turn conversation

• No defined workflow or steps

• No tool integration by default

• Quality depends heavily on phrasing

Prompts are the foundation. Everything else builds on top of them.

An agent is an AI model with a loop: it can reason, take actions (call tools, read files, run commands), observe results, and decide what to do next. It has autonomy.

Agent: "I need to fix this bug. Let me read the error log...
        OK, the issue is in auth.service.ts line 42...
        Let me read that file... I see the problem...
        Let me edit the file... Now let me run the tests...
        Tests pass. Done."

An agent doesn't just answer — it acts. It has a tool belt (file system access, API calls, shell commands) and uses reasoning to decide which tools to invoke and in what order.

Characteristics of agents:

• Stateful within a session (remembers what it's done)

• Autonomous — makes decisions about next actions

• Has tools (file read/write, shell, APIs, MCP servers)

• Can handle multi-step tasks without human intervention

• Quality depends on reasoning ability and available tools

Agents are powerful but unpredictable. Without guidance, they improvise. Sometimes brilliantly. Sometimes disastrously.

A skill is a reusable instruction set that teaches an agent how to perform a specific task. It's not a prompt (it's structured and multi-step). It's not an agent (it doesn't reason on its own). It's the bridge between them.

---
name: fix-duplicates
description: Find and fix duplicate code using jscpd
user_invocable: true
---

# Fix Duplicates

## Steps

### 1. Run jscpd
bunx jscpd <path> --reporters json --output /tmp/jscpd-report

### 2. Read the Report
Parse /tmp/jscpd-report/jscpd-report.json

### 3. Decide: Refactor or Ignore
**Refactor when ALL apply:**
- 10+ lines of non-trivial logic
- Same module/domain
- Clean extraction possible

**Ignore when ANY apply:**
- Import blocks or boilerplate
- Cross-domain coupling risk
- < 10 lines and simple

A skill is a recipe that an agent follows. The agent still reasons (it decides how to implement each step), but the skill provides the what and when.

Characteristics of skills:

• Declarative — defines what to do, not how to think

• Structured — YAML metadata + markdown instructions

• Reusable — works across projects and agents

• Versionable — lives in your repo, goes through code review

• Composable — skills can be chained into workflows

• Loaded on demand — only enters context when relevant

Think of it as layers:

┌─────────────────────────────┐
│         Skills              │  ← Structured workflows
│    (what to do, when)       │
├─────────────────────────────┤
│         Agents              │  ← Reasoning + tool use
│    (how to think, act)      │
├─────────────────────────────┤
│         Prompts             │  ← Raw instructions
│    (what to generate)       │
└─────────────────────────────┘

• Prompts tell the model what to produce.

• Agents give the model the ability to act on the world.

• Skills give the agent structured knowledge about how to perform specific tasks.

An agent without skills is like a talented engineer who just joined your company. They can code, reason, and use tools — but they don't know your conventions, your deployment process, or where to find the config files.

A skill is the onboarding document that turns a capable generalist into a productive team member.

• The task is a single, well-defined question or generation

• No tools or external actions are needed

• The output is text (code, copy, analysis) — not an action

• You're exploring or prototyping, not automating

Examples:

• "Explain this error message"

• "Write a regex that validates phone numbers"

• "Summarize this pull request"

• "Draft a tweet about our new feature"

• The task requires multiple steps with tool use

• You need file system access, API calls, or shell commands

• The task involves reading, reasoning, and acting

• Each run is different enough that a fixed workflow doesn't make sense

Examples:

• "Debug this failing test and fix it"

• "Set up a new module with all the boilerplate"

• "Research this library and recommend if we should adopt it"

• "Review this PR for security issues"

• You have a repeatable workflow that should produce consistent results

• The task follows a defined process (steps, decisions, verification)

• Multiple agents or team members need to execute the same workflow

• Quality and consistency matter more than flexibility

• You want the workflow to be versioned and reviewable

Examples:

• "Process the next ticket from the backlog" (Ralph skill)

• "Scan the codebase for security annotation gaps" (Security Annotate skill)

• "Find and fix code duplicates" (Fix Duplicates skill)

• "Create a database migration following our conventions" (Migrations skill)

Here's the practical test. Run the same task 10 times:

Prompts degrade because the model has no memory of previous runs. Agents are better because they can reason about the task, but they'll vary in approach. Skills produce consistent results because the workflow is defined — the agent fills in the details, but the structure stays the same.

This is why skills matter for production systems. A 90% success rate sounds good until you realize that means 1 in 10 runs produces garbage that a human has to fix.

No. System prompts are loaded for every interaction and compete for context window space. Skills are loaded on demand — only when the agent encounters a matching task. A system prompt of 10,000 words degrades model performance. Thirty skills of 300 words each load individually and stay focused.

No. Skills provide structure; agents provide intelligence. A skill says "run jscpd and parse the report." The agent figures out how to handle the specific duplicates it finds. The skill is the recipe; the agent is the chef.

Partially true at the model level, but misleading in practice. The key difference is the tool-use loop. An agent can observe the result of an action and decide its next action based on that result. A prompt generates one response. This feedback loop is what enables multi-step task completion.

No. You use all three together. The prompt is the user's request. The agent is the execution engine. The skill is the domain knowledge. They're layers, not alternatives.

If you've been using prompts or bare agents, here's how to upgrade to skills.

Step 1: Identify the pattern.

Look at your last 20 agent interactions. Which tasks did you repeat? Which ones required you to re-explain the same process? Those are your skill candidates.

Step 2: Write the workflow.

Document the exact steps, decisions, and tools involved. Be specific:

## Steps

### 1. Run the linter
bunx eslint src/ --format json --output-file /tmp/lint-report.json

### 2. Parse results
Read /tmp/lint-report.json. Count errors by rule.

### 3. Fix the top 3 most common errors
For each error type, apply the fix across all occurrences.

### 4. Verify
Re-run the linter. Confirm error count decreased.

Step 3: Add decision criteria.

If any step requires judgment, encode it:

**Auto-fix when:**
- The rule has a well-known fix (unused-vars, missing-semicolons)
- The fix doesn't change behavior

**Skip when:**
- The rule is style-only and the team hasn't agreed on a standard
- The fix might change runtime behavior

Step 4: Add guardrails.

What should the agent NOT do?

## Rules
- Do NOT modify test files.
- Do NOT change code formatting beyond what the linter requires.
- Do NOT install new packages.

Step 5: Save it.

.claude/skills/lint-fixer/SKILL.md

Commit it. Your agent now has a new capability.

Claude Code has .claude/skills/. Other AI coding tools have similar concepts emerging under different names. The pattern is the same: structured, reusable instruction sets that agents can load on demand.

This convergence is happening because every team that scales AI agent usage hits the same problem: inconsistency at scale. One agent run is great. A hundred runs per day with varying quality is unsustainable.

Skills are the answer because they capture what works and make it repeatable. They're the missing layer between "AI can do anything" and "AI does this specific thing reliably."

Use this when deciding how to approach a new AI-assisted task:

Is this a one-off question or generation?
  → Yes → Use a prompt.
  → No ↓

Does it require tools (file access, APIs, commands)?
  → No → Use a prompt (maybe a detailed one).
  → Yes ↓

Will you do this task more than 3 times?
  → No → Use an agent with ad-hoc instructions.
  → Yes ↓

Does consistency matter?
  → No → Use an agent.
  → Yes → Write a skill.

Most tasks start as prompts. The ones that recur become agent workflows. The workflows that need consistency become skills. It's a natural progression, not a choice you make upfront.

Skills are still early. The format is simple (YAML + markdown), the tooling is basic, and there's no marketplace or standard library yet. But the pattern is proven: structured, reusable instruction sets make AI agents dramatically more reliable.

The teams that invest in skills now will have a compounding advantage. Every skill you write makes your agents better. Every improvement to a skill benefits every agent that uses it. It's infrastructure that pays dividends.

Start with one skill. Then five. Then twenty. By the time the ecosystem standardizes, you'll already have a library that works.

Follow Arjia for more on AI agent architecture: Twitter | Discord | Telegram

This article is part of Arjia's AI Agent Skills series. Previous: "The Definitive Guide to AI Agent Skills" | "How We Run a 30-Agent Company on Skills"