Skill vs tool vs prompt

Three layers, one agent stack

When you ship an agent, you are not choosing between a prompt, a tool, or a skill — you are deciding where knowledge and procedure live in the stack. A prompt is ephemeral context: instructions injected at call time that tell the model how to behave for this turn or session. A tool is executable capability: a function with a schema the model can invoke to read or mutate the world. A skill sits between them — a durable, versioned package of domain procedure, examples, and guardrails that the host loads when relevant.

Think of prompts as sticky notes, tools as APIs, and skills as playbooks. Sticky notes are cheap to change but easy to lose; APIs are rigid but testable; playbooks encode how experts work in a narrow domain without hard-coding every branch in application code.

The confusion usually appears because all three show up as text in the context window. The distinction is operational:

• Prompts are assembled per request and rarely versioned independently.
• Tools return structured results and have side effects you must audit.
• Skills are files (often Markdown) with metadata, loaded selectively, and reviewed like code.

Callout — Why this matters for production: Demo agents dump a 4,000-token system prompt and call it done. Production agents split stable procedure into skills, keep tool schemas lean, and reserve the live prompt for session-specific state (user identity, current task, retrieved chunks). That split is what makes iteration safe.

Prompts: flexible, fragile

System and developer prompts excel at session framing: tone, safety boundaries, output format, and the current user goal. They are the right place for values that change every turn — "You are helping Akshant debug a failing CI job" — and for constraints that must apply globally, such as "never exfiltrate secrets from tool outputs."

Prompts fail as the primary store of domain knowledge because:

• They bloat the context window and compete with retrieval, memory, and tool results.
• They are hard to diff, review, and A/B test when mixed with runtime variables.
• They encourage copy-paste drift: one team member updates the prompt in code, another in a dashboard.

Rule of thumb: If the text would be identical across 80% of sessions for a given product surface, it probably should not live only in a prompt.

Example split for a support agent:

• Prompt (session): customer tier, open ticket ID, language preference.
• Skill (durable): refund policy decision tree, escalation triggers, phrasing for empathetic denials.
• Tool (executable): lookup_order, issue_refund, create_escalation.

Tools: contracts with consequences

Tools are the agent's hands. Each tool exposes a name, description, JSON schema for arguments, and an implementation. The model chooses tools based on descriptions; bad descriptions cause wrong calls more often than weak reasoning.

Good tool design for agents mirrors good API design for humans:

• Narrow scope — prefer search_invoices_by_date over do_billing_stuff.
• Structured outputs — return JSON the model can parse; avoid prose dumps.
• Explicit failure modes — return { "error": "ORDER_NOT_FOUND", "hint": "..." } instead of stack traces.
• Idempotency keys on mutating operations (you will harden this in later production lessons).

Tools are not skills. A tool runs code; a skill teaches procedure. "How to triage a P1 incident" belongs in a skill; "page_oncall(engineer_id)" belongs in a tool.

Skills: procedure you can ship and review

A skill packages what a senior engineer would whisper to a junior: checklists, examples of good and bad outcomes, edge cases, and links to internal conventions. Cursor, Claude Code, and similar hosts popularized SKILL.md files — but the pattern generalizes to any agent host.

A minimal skill package might include:

skills/refund-triage/
  SKILL.md          # procedure + examples + when-to-use
  metadata.yaml     # name, description, tags, token budget hint
  examples/
    approved.jsonl
    rejected.jsonl

The host agent indexes skill descriptions (cheap) and loads full bodies only when selected (expensive). That two-stage pattern is the bridge to dynamic loading in the next lesson.

Skills shine when:

• Procedure is stable but branching (compliance workflows, code review rubrics).
• You need few-shot examples without stuffing the system prompt.
• Multiple agents share the same playbook (support bot + internal copilot).

Choosing the right layer

Use this decision table when inventorying your agent from the prior agent module:

Callout — Common anti-pattern: Encoding business logic only in tool descriptions ("If the order is older than 30 days, call refund_partial with…"). Descriptions are not executable; the model will drift. Put the decision tree in a skill; keep the tool description factual.

Designing your skill package format

Before authoring skills, agree on a host contract so loading, logging, and testing stay uniform. Your format should answer:

1. Discovery — How does the agent list available skills? (YAML frontmatter description field, max 200 chars.)
2. Activation — Who selects the skill — router model, keyword match, or explicit user command?
3. Budget — Max tokens injected per skill; what gets truncated first (examples vs. narrative)?
4. Versioning — Semver in metadata; breaking changes require a migration note.

Document the format in content/modules/m8/ or your portfolio's skills/README.md before writing skill bodies. The micro-project turns this document into an executable spec your host can parse.

Engineering problem (staff framing)

Clarify units: prompts shape behavior; tools do IO; skills package procedures/knowledge for agents.

Diagram — Prompt / tool / skill

flowchart TD
  Prompt[Prompt policy] --> Agent
  Skill[Skill pack] --> Agent
  Tool[Tools RPC] --> Agent

Precise definitions & mental model

Skill as versioned procedure+resources; not a synonym for tool.

Tradeoffs — when to use what

Fat prompts vs modular skills — cacheability and ownership.

Failure modes (interview + on-call)

Everything in one system prompt; skills that silently call mutating tools.

Production & OSS practices

Version skills; load on demand; review like code.

Micro-project: Skill package format

In your course-portfolio repo under the skills module folder:

1. Write SKILL_FORMAT.md defining required fields (name, description, triggers, body sections, example blocks, failure notes).
2. Include a JSON or YAML schema snippet your host will validate against.
3. Inventory your hand-rolled agent from the agent module: list ≥5 behaviors and classify each as prompt, tool, or skill candidate.
4. Promote at least two prompt-only blobs to skill-shaped files (even if stub content) to prove the format works.
5. Add a one-page diagram: prompt vs. tool vs. skill flow for one user request.

Acceptance: a teammate (or future you) can add a new skill without reading the host source code.

Checklist

• Skill format doc committed with schema
• Inventory table: prompt / tool / skill classification
• Two stub skills loadable from disk in the host
• Diagram or sequence sketch for one end-to-end request
• Module README updated with format decisions and open questions