Skill Mental Model

Why do we need a separate concept of a “skill”?

Recurring tasks appear quickly in LLM applications:

• reviewing a pull request,
• classifying a support ticket,
• summarizing an incident,
• extracting invoice data,
• checking a deployment,
• updating documentation.

Each of these could be expressed as a new prompt every time, but larger systems soon need a more stable abstraction.

A useful mental model for an Agent Skill is:

A reusable, named and bounded capability that defines how an AI system should perform a particular class of tasks.

A skill is not necessarily just a prompt. It may contain:

Skill
├── purpose
├── instructions
├── input contract
├── output contract
├── knowledge / context policy
├── tools
├── examples
├── constraints / permissions
└── success / evaluation criteria

The term skill is not universally standardized. Different platforms may use it differently. In this knowledge base, it is an engineering abstraction: a reusable capability contract.

Prompt vs Skill vs Tool vs Workflow vs Agent

These concepts are easy to blur together, even though they live at different levels.

Concept	Primary role
Prompt	Instructions and context for one model interaction
Tool	External operation or data source the system can invoke
Skill	Reusable task-level capability and its contract
Workflow	Predefined steps and control flow
Agent	Runtime that can make decisions toward a goal and use capabilities

Prompt

A prompt might be:

Review this pull request.
Focus on correctness, architecture and backwards compatibility.
Return findings ordered by severity.

That is an instruction by itself.

If the same behavior is needed in several places, with a stable input/output format, fixed evaluation dimensions, and GitHub-reading tools, it becomes useful to model it as a skill.

Tool

A tool is a concrete capability:

get_pull_request_diff(pr_number)
read_repository_file(path)
run_tests(test_scope)

The tool does not explain why, when, or how a PR should be reviewed. It only provides an operation.

The PR review skill can use those tools.

PR Review Skill
      │
      ├── read_repository_file
      └── get_pull_request_diff

So:

A tool is a mechanical capability; a skill is a task-level capability.

Workflow

A workflow may define explicit control flow:

1. Fetch PR diff
2. Run static analysis
3. Run tests
4. Ask model for review
5. Publish report

Most steps are predetermined by the application.

A skill, by contrast, primarily defines how a capability should be performed, not necessarily the entire end-to-end process.

Agent

An agent is a higher-level runtime:

Goal
 ↓
Agent
 ├── PR Review Skill
 ├── Test Failure Analysis Skill
 ├── Documentation Skill
 └── tools

The agent may decide that solving the task requires analyzing a test failure first and then running a PR review.

A skill is therefore not the agent itself. One agent can use multiple skills.

Reusable capability vs one-off instruction

Not every prompt needs to become a skill.

One-off request:

Rewrite this email to sound more polite.

This probably does not justify a separate skill architecture.

But if an application generates every customer-escalation email according to the same policy, with auditable output and CRM data, a reusable capability may be justified:

Customer Escalation Response Skill

A skill starts to add value when several of these matter:

• the capability is used repeatedly,
• multiple agents or workflows use it,
• a stable input/output contract is needed,
• tools belong to it,
• domain rules must be followed,
• it should be evaluated independently,
• it should be versioned independently,
• it has a security or permission boundary.

Example: GitHub PR Review Skill

A task-level mental model:

Name:
  review_pull_request

Purpose:
  Identify material correctness and architecture risks in a PR.

Inputs:
  repository
  pull_request
  review_focus

Instructions:
  Focus on correctness, architecture, regressions and tests.
  Do not invent code outside the supplied/retrieved repository state.

Tools:
  fetch_diff
  read_file
  read_tests

Output:
  findings[]
  summary
  confidence

Constraints:
  read-only
  never merge or modify the PR

The runtime can use these pieces to assemble the actual model input and tool set.

The important abstraction is:

Application asks for capability
          ↓
    PR Review Skill
          ↓
 model + context + tools
          ↓
      typed result

The application no longer has to know all prompt details for every call.

Skill boundary: what belongs in one skill?

A good skill has one coherent responsibility.

A reasonable boundary:

Analyze Test Failure

Possibly too small:

Explain One Stack Trace Line

Too broad:

Develop Software

A very large skill usually mixes independent capabilities:

Mega Coding Skill
├── requirements analysis
├── architecture
├── coding
├── testing
├── deployment
├── documentation
└── incident response

Then it becomes hard to answer:

• what input it needs,
• which tools it may access,
• what counts as success,
• how to evaluate it,
• where it failed.

Better:

Requirements Analysis Skill
Architecture Review Skill
Implementation Skill
Test Failure Analysis Skill
Documentation Update Skill

A workflow or agent can compose these later.

A skill is not necessarily one model call

A skill implementation can be simple:

input → LLM → output

But it can also be more involved:

input
 ↓
retrieve context
 ↓
LLM selects tool
 ↓
tool result
 ↓
LLM produces structured result

It can even contain several deterministic steps.

This is why it is important to separate:

Skill interface
      ≠
Skill implementation

The same skill contract can later be implemented with a different model, prompt, or tool backend.

This is the same thinking used for a well-designed software interface.

Capability vs implementation

For example, a skill might be called:

Get Current Deployment Health

The skill should not promise:

Use Kubernetes API v1 with tool X.

The capability is better described as:

Given a deployment target, return its current health and material problems.

The runtime may implement it with:

Kubernetes tool

and later with:

Argo CD tool

The skill is less coupled to infrastructure details.

Anti-pattern: every prompt is a skill

If every small instruction becomes a separate skill:

summarize_text
summarize_short_text
summarize_long_text
summarize_markdown
summarize_email
summarize_ticket
...

then the skill registry itself becomes a source of complexity.

A reusable abstraction is useful only when there is a genuinely stable and separate responsibility.

Anti-pattern: “skill = system prompt”

A skill can be only an instruction package if a particular platform uses that model.

But architecturally it is dangerous to always think:

skill = prompt text

because important elements disappear:

• input/output contract,
• tool dependency,
• permission boundary,
• version,
• failure semantics,
• evaluation.

A better mental model:

skill
  ↓
capability contract
  ↓
one possible implementation
  ↓
prompt + model + tools

Anti-pattern: the skill as an authorization authority

If a skill instruction says:

Only delete test environments.

we still must not rely on the model to delete only test environments.

The skill may state the rule, but the application must enforce it deterministically:

LLM requests delete
       ↓
application authorization
       ↓
environment == TEST ?
       ↓
execute / reject

A skill is a behavioral abstraction, not a security boundary by itself.

When should we not introduce a skill?

A system may be simpler without the skill abstraction when:

• there is only one one-off model call,
• there is no reusable behavior,
• there is no separate tool or contract,
• independent versioning/evaluation is unnecessary,
• deterministic code solves the task more simply.

The goal is not to turn everything into an agentic abstraction.

The goal is:

Use a skill where a stable task-level capability with its own name, contract, and lifecycle genuinely reduces system complexity.

Takeaways

• Skill is not a universal standard; it is a useful engineering abstraction.
• A skill is a reusable task-level capability, not merely a prompt.
• A prompt instructs, a tool provides an operation, a workflow defines control flow, and an agent can choose and use capabilities.
• Skill interface and implementation should be separable.
• A good skill has a coherent responsibility and clear boundary.
• Do not create a skill for every small prompt, and avoid all-knowing mega-skills.
• Skill instructions do not replace application authorization and validation boundaries.