Agent Skills

When I first started exploring agentic automation, one thing became clear very quickly: a powerful AI model is not the same thing as a reliable digital worker. A model can reason, summarize, write code, classify a document, or draft a response. But when we ask it to repeatedly perform a real business task, the challenge becomes different. We do not just need intelligence. We need repeatability.

We need the agent to know:

When should I use this workflow?
What steps should I follow?
Which tools are allowed?
Which data sources are trusted?
What should I avoid?
When do I ask for human approval?
What should the final output look like?

This is where a Skill file, usually written as SKILL.md, becomes important.

In simple words, a Skill file is like an operating manual for an AI agent. It packages task-specific instructions, examples, references, scripts, assets, and guardrails so the agent can perform a workflow more consistently. The more I work with agents, the more I see Skill files as one of the most practical building blocks for enterprise agentic automation.

1. The Problem: Agents Are Powerful, But Often Inconsistent

Imagine asking an AI agent:

Prepare a customer renewal brief for ACME before tomorrow's meeting.

A good agent may know that it needs to gather CRM data, recent meeting notes, open support tickets, product usage, renewal date, risks, and next steps.But without a reusable workflow, each run may look slightly different. One time it may include support risks. Another time it may forget product usage. Another time it may draft a great summary but miss open escalations. Another time it may call a tool too early or use an outdated template.

This is the gap between a smart assistant and a reliable agent.

A business process needs consistency. A human team solves this with standard operating procedures, checklists, templates, playbooks, and review gates. An AI agent needs the same thing in a form it can discover and execute. That is the role of a Skill file.

2. What Is a Skill File?

A Skill file is a structured instruction file that tells an AI agent how to perform a specific task or workflow.

In many agent environments, the main file is called:

SKILL.md

The file usually lives inside a skill folder. That folder may also include supporting scripts, reference documents, templates, sample outputs, or configuration files.

A simple skill folder may look like this:

invoice-exception-triage/
  SKILL.md
  scripts/
    normalize_invoice.py
  references/
    invoice-policy.md
    approval-rules.md
  assets/
    exception-summary-template.md
  agents/
    openai.yaml

The SKILL.md file is the heart of the skill. It describes the skill name, when it should be used, and the workflow the agent should follow.

A minimal SKILL.md may look like this:

---
name: invoice-exception-triage
description: Use when a finance agent needs to investigate invoice mismatch exceptions, compare invoice, purchase order, goods receipt, and vendor data, and recommend the next action. Do not use for payment release approval.
---

# Invoice Exception Triage Skill

## Goal
Help the agent investigate invoice mismatches in a consistent, controlled, and auditable way.

## When to use
- The user asks to review an invoice exception.
- The user provides an invoice ID, vendor name, or exception case ID.
- The task involves comparing invoice, PO, GRN, vendor, and approval rule data.

## Do not use
- Do not release payments.
- Do not approve invoices.
- Do not send emails externally without user approval.

## Workflow
1. Confirm the invoice ID and vendor.
2. Retrieve invoice, PO, GRN, and vendor master data.
3. Compare amount, quantity, tax, payment terms, and approval status.
4. Identify the likely exception reason.
5. Recommend the next action.
6. Ask for human approval before creating or updating any case.

## Output format
Return:
- Exception summary
- Evidence checked
- Likely root cause
- Recommended next action
- Approval required: yes or no

Notice something important: this is not just a prompt. It is a reusable workflow definition.

3. Why Agents Need Skill Files

I think of Skill files as the agent's job-specific memory. A general model may know how to reason, but it does not automatically know how your organization wants a workflow done. It does not know your naming conventions, review process, escalation rules, output format, or safety boundaries unless you tell it.

A Skill file gives the agent that reusable operating knowledge.

Without a Skill File

The user prompt carries most of the responsibility.

User request -> Agent guesses the workflow -> Agent uses tools -> Output varies

This can work for simple tasks, but it becomes fragile for enterprise workflows.

With a Skill File

The workflow becomes reusable.

User request -> Agent selects skill -> Agent follows workflow -> Output is consistent

A good Skill file helps with:

• consistency across repeated tasks

• fewer missing steps

• clearer tool usage

• better output structure

• safer execution boundaries

• easier review and improvement

• reusable knowledge across teams

For me, this is the big shift. Prompting tells an agent what to do now. A skill teaches the agent how to do a class of work repeatedly.

4. Architecture: Where the Skill File Fits

At a high level, a skill sits between the user's request and the agent's execution layer.

The flow looks like this:

User Request
   -> Agent Host
      -> Skill Selector
         -> SKILL.md Package
            -> Tools, Context, Scripts, Controls
               -> Structured Output

The agent host manages the conversation, the model, permissions, and available tools. The skill selector decides whether a skill is relevant. The Skill file then gives the agent the task-specific workflow.

This makes the agent more reliable because it does not need to reconstruct the process from scratch every time.

5. Skill File vs Prompt vs Tool vs MCP

It is useful to separate these concepts because they are often mixed together.

Prompt

A prompt is an instruction for the current interaction.

Example:

Summarize this meeting transcript in five bullet points.

A prompt is flexible, but often temporary.

Tool

A tool is something the agent can call to do work.

Example:

get_customer_record(customer_id)
create_support_ticket(ticket_details)
query_invoice_status(invoice_id)

A tool gives the agent capability, but it does not fully explain the business process.

MCP Server

A Model Context Protocol server exposes tools, resources, and prompts from external systems in a standard way. It helps the agent connect to systems such as databases, SaaS applications, repositories, or internal services.

Skill File

A Skill file tells the agent how and when to use prompts, tools, data, references, and checks for a specific workflow.

So I like this simple distinction:

Prompt  -> what to do now
Tool    -> what action is possible
MCP     -> how external systems are exposed
Skill   -> how to complete a workflow reliably

A skill does not replace tools. It guides tool usage.

A skill does not replace MCP. It can explain how an agent should use MCP-exposed tools and resources.

A skill does not replace governance. It should include governance instructions and connect to enterprise controls.

6. Anatomy of a Skill Package

A good skill package usually has five parts.

1. Metadata

The metadata tells the agent what the skill is and when to consider it.

---
name: customer-renewal-brief
description: Use when preparing a customer renewal or account briefing using CRM, support, product usage, meeting notes, and risk data. Do not use for legal contract approval.
---

The description is extremely important. Many agents first see only the skill name and description before deciding whether to load the full instructions. If the description is vague, the skill may not trigger when needed or may trigger at the wrong time.

A weak description:

Helps with customer tasks.

A stronger description:

Use when preparing an executive customer renewal brief that combines CRM opportunity data, support risks, product usage, renewal timeline, and recommended next steps. Do not use for contract negotiation or pricing approval.

The stronger version includes trigger words, scope, data sources, and boundaries.

2. Goal

The goal explains the purpose of the skill in plain language.

## Goal
Prepare a concise, executive-ready renewal brief that helps an account team understand customer health, renewal risk, and next best actions before a meeting.

3. When to Use and When Not to Use

This section avoids misuse.

## When to use
- The user asks for a renewal brief.
- The user asks for account risk summary.
- The user asks to prepare for a customer meeting.

## Do not use
- Do not approve discounts.
- Do not change opportunity stage without approval.
- Do not send customer-facing communication without user confirmation.

This is where a Skill file becomes more than documentation. It becomes a control surface for agent behavior.

4. Inputs and Data Sources

A skill should clearly define what information the agent needs.

## Required inputs
- Account name or account ID
- Meeting date or renewal period

## Data sources
- CRM account and opportunity records
- Recent meeting notes
- Open support tickets
- Product usage metrics
- Renewal history

5. Workflow Steps

The workflow should be direct and operational.

## Workflow
1. Confirm the account name and renewal period.
2. Retrieve CRM opportunity and account data.
3. Review recent meeting notes.
4. Check support ticket history and escalations.
5. Review product usage trends.
6. Identify renewal risks and expansion opportunities.
7. Draft the brief using the approved template.
8. Highlight missing data instead of guessing.

6. Output Format

The output format helps make results consistent.

## Output format
Return the brief with these sections:

1. Executive summary
2. Renewal timeline
3. Customer health
4. Open risks
5. Expansion opportunities
6. Recommended next actions
7. Missing information

7. Safety and Approval Rules

For enterprise use, this is one of the most important sections.

## Safety and approval rules
- Read-only by default.
- Ask for approval before updating CRM.
- Ask for approval before creating a support escalation.
- Never expose confidential notes in a customer-facing draft.
- Log every system update with account ID, user, timestamp, and reason.

7. How the Agent Uses a Skill File

A useful way to understand skills is through the lifecycle.

Step 1: Agent sees available skill names and descriptions
Step 2: User asks for a task
Step 3: Agent matches the task to a skill description
Step 4: Agent loads the full SKILL.md instructions
Step 5: Agent follows the workflow
Step 6: Agent uses tools, scripts, references, and templates if allowed
Step 7: Agent checks approval and safety rules
Step 8: Agent returns the final output

This is powerful because the agent does not need to carry every long workflow in the main prompt. It can discover the right skill when needed.

That pattern is called progressive disclosure: show the agent enough information to select the right skill, then load deeper instructions only when necessary.

8. Types of Skills Agents Can Use

Not every skill needs to be complex. I like to think about skills in levels.

1. Instruction-Only Skill

This is the simplest type.

It contains only SKILL.md.

Best for:

Writing style guides
Review checklists
Meeting summary formats
Incident triage steps
Customer briefing templates

Example:

A skill that tells the agent how to write executive updates in a specific format.

2. Reference-Backed Skill

This skill includes reference documents.

references/
  support-severity-policy.md
  escalation-rules.md
  refund-policy.md

Best for:

Policy interpretation
Support operations
Compliance workflows
HR procedures
Finance exception handling

The skill instructs the agent when and how to consult those references.

3. Script-Backed Skill

This skill includes deterministic helper scripts.

scripts/
  validate_invoice_totals.py
  normalize_vendor_name.py
  generate_summary_table.py

Best for:

Data transformation
Validation
File conversion
Repeatable calculations
Codebase maintenance

The agent can use the script when natural language reasoning is not precise enough.

4. Template-Backed Skill

This skill includes approved output templates.

assets/
  customer-renewal-brief-template.md
  incident-report-template.md
  jira-ticket-template.md

Best for:

Executive briefs
Status reports
Release notes
Customer emails
Risk summaries

This is extremely useful in enterprises because output consistency matters.

5. Tool-Connected Skill

This skill explains how the agent should use tools.

Example:

Use get_account() before get_opportunities().
Use list_support_tickets() only after confirming account ID.
Never call update_opportunity() without user approval.

Best for:

CRM automation
Finance operations
IT service management
DevOps workflows
Customer support actions

6. MCP-Connected Skill

This skill guides the use of MCP-exposed tools and resources.

Example:

For invoice triage, read invoice://{id}, purchase-order://{id}, and vendor://{id}. Call create_exception_case only after presenting evidence and receiving approval.

The MCP server provides the tools and resources. The Skill file provides the business workflow.

7. Repository-Scoped Skill

For coding agents, a repository-scoped skill can explain project-specific conventions.

Example:

Use this skill when modifying payment-service code. Always run unit tests, contract tests, and schema checks before proposing a pull request.

This helps the agent follow the team's engineering standards instead of generic coding advice.

9. Practical Example: Customer Renewal Brief Skill

Let us create a small but realistic skill.

Folder structure:

customer-renewal-brief/
  SKILL.md
  references/
    renewal-risk-signals.md
    account-health-rubric.md
  assets/
    renewal-brief-template.md

SKILL.md:

---
name: customer-renewal-brief
description: Use when preparing an executive customer renewal or account meeting brief using CRM, support, product usage, meeting notes, risks, and next actions. Do not use for pricing approval or legal contract review.
---

# Customer Renewal Brief Skill

## Goal
Create a clear, executive-ready renewal brief that helps account teams prepare for customer conversations.

## When to use
- User asks to prepare for a customer meeting.
- User asks for renewal risk summary.
- User asks for account health or customer briefing.

## Do not use
- Do not approve pricing, discounts, or contract changes.
- Do not send customer-facing communication without approval.
- Do not update CRM fields unless the user explicitly approves the change.

## Required inputs
- Account name or account ID
- Renewal period or meeting date

## Workflow
1. Confirm the account and meeting context.
2. Retrieve CRM account and opportunity data.
3. Review recent meeting notes and emails if available.
4. Check open support tickets and escalations.
5. Review product usage and adoption trends.
6. Compare findings against renewal risk signals.
7. Draft the brief using the approved template.
8. Clearly mark missing information.
9. Recommend next actions for the account team.

## Output format
Return the brief with:
- Executive summary
- Renewal timeline
- Customer health
- Key risks
- Expansion opportunities
- Recommended next actions
- Missing information

## Safety rules
- Read-only by default.
- Ask before updating CRM.
- Ask before creating tasks or tickets.
- Do not include confidential internal notes in customer-facing content.

This skill gives the agent a repeatable playbook.

Now the user can ask:

Prepare a renewal brief for ACME for tomorrow's QBR.

The agent can recognize the task, load the skill, follow the workflow, retrieve the right context, and produce a consistent brief.

10. How This Maps to Enterprise Agentic Automation

Skill files become especially useful when organizations move from one-off chatbot use cases to repeatable work.

Here are some examples.

Finance Operations

invoice-exception-triage
vendor-master-review
payment-block-summary
month-end-close-checklist

A finance skill can guide the agent to compare invoice, PO, GRN, tax, vendor, and approval data before recommending a next action.

Customer Support

case-escalation-summary
refund-policy-review
sla-breach-triage
customer-response-draft

A support skill can ensure the agent checks entitlement, severity, SLA, previous interactions, and policy before drafting a response.

Sales and Account Management

customer-renewal-brief
opportunity-risk-review
account-meeting-prep
executive-update-draft

A sales skill can standardize how account teams prepare for renewals and executive meetings.

Software Engineering

code-change-verification
release-note-generation
bug-repro-analysis
security-review-checklist

A coding skill can encode repository-specific build, test, and review expectations.

HR and Employee Service

policy-answering
onboarding-checklist
role-change-summary
employee-ticket-triage

An HR skill can guide the agent to use approved policies and avoid unauthorized advice or action.

11. Skill File Design Patterns

Over time, I have found a few design patterns useful.

Pattern 1: One Skill, One Job

Avoid creating a giant skill that tries to handle everything.

Weak skill:

enterprise-assistant

Better skills:

invoice-exception-triage
customer-renewal-brief
incident-postmortem-draft
code-change-verification

Focused skills are easier to trigger, test, govern, and improve.

Pattern 2: Strong Trigger Description

The description should answer:

When should this skill be used?
When should it not be used?
Which task words should trigger it?

Example:

description: Use when preparing an incident postmortem from timeline, alerts, logs, impact, root cause, and corrective actions. Do not use for live incident response or production changes.

Pattern 3: Read-Only First

For early adoption, start with skills that read data and produce recommendations.

Then move to skills that create drafts.

Only later allow skills that update systems, create tickets, send messages, or trigger workflows.

A safe maturity path:

Read -> Summarize -> Recommend -> Draft -> Create with approval -> Execute with policy

Pattern 4: Use Scripts for Deterministic Work

Do not ask the model to calculate or transform data manually when a script can do it reliably.

Good candidates for scripts:

CSV validation
schema checks
invoice total comparison
test execution
log parsing
file conversion

Pattern 5: Explicit Output Contract

Agents perform better when the expected output is clear.

Instead of saying:

Write a summary.

Use:

Return the output with these sections: executive summary, evidence checked, risks, recommendation, approval needed, missing information.

Pattern 6: Built-In Escalation Rules

A good skill should tell the agent when to stop and ask.

Ask the user before external communication.
Ask the user before write actions.
Ask the user if required data is missing.
Ask the user if confidence is low.

12. Security: The Most Important Part

Skill files are powerful because they influence how an agent behaves.

That also makes them risky.

A malicious or poorly written skill could tell an agent to leak files, call dangerous tools, ignore approvals, or hide actions. A skill can also include scripts, references, or assets that the agent may use during execution.

So I would treat skills like production automation assets, not casual prompt snippets.

Here are the controls I would recommend.

1. Review Every Skill Before Use

Do not install random skills from untrusted repositories without inspection.

Review:

SKILL.md instructions
scripts
references
assets
network calls
tool dependencies
hidden or indirect instructions

2. Use Least Privilege

A skill should only have access to the tools and data it needs.

An invoice triage skill may need read access to invoice and PO data. It should not automatically have permission to release payments.

3. Gate Sensitive Actions

Require approval before actions such as:

sending emails
updating CRM
approving invoices
releasing payments
deleting records
creating external tickets
executing shell commands

4. Validate Inputs and Outputs

Validate anything the skill receives before using it in tools or scripts.

Also validate what the agent produces before passing it to downstream systems.

5. Log Every Important Action

For enterprise adoption, logs are non-negotiable.

Track:

which skill was used
which user requested it
which tools were called
what data was accessed
what changes were made
which approvals were captured

6. Version Skills

A skill is not static. It should improve as the process evolves.

Use version control so teams can see what changed, who approved it, and how to roll back.

7. Red-Team Skill Injection

Skill files can become an attack surface. Test whether malicious instructions inside references, templates, comments, or scripts can influence the agent.

This is especially important when skills come from outside your organization.

13. Skill File Checklist

Before using a skill in production, I would check these items.

1. Does the skill have one clear job?
2. Is the description specific enough for correct triggering?
3. Does it define when not to use the skill?
4. Does it define required inputs?
5. Does it define trusted data sources?
6. Does it include clear workflow steps?
7. Does it define the output format?
8. Does it separate read actions from write actions?
9. Does it require approval for sensitive actions?
10. Are scripts reviewed and safe?
11. Are references trusted and current?
12. Is the skill versioned and owned?
13. Is usage logged?
14. Has it been tested with realistic prompts?
15. Has it been tested against prompt injection?

14. Common Mistakes to Avoid

Mistake 1: Writing a Skill Like a Long Prompt

A skill should not be a random wall of instructions.

It should be structured, scoped, and testable.

Mistake 2: Vague Descriptions

If the description is vague, the agent may not select the skill correctly.

Mistake 3: Too Many Responsibilities

A skill that handles finance, HR, IT, and sales will become hard to govern.

Mistake 4: No Safety Boundaries

A skill without approval rules can become dangerous when connected to real tools.

Mistake 5: No Output Contract

If the output format is not defined, every response may look different.

Mistake 6: Trusting External Skills Blindly

A skill can contain harmful instructions or scripts. Treat it like code.

15. Visual Summary

A useful skill file should help the agent answer six questions:

1. What job am I doing?
2. When should I use this workflow?
3. What information do I need?
4. What steps should I follow?
5. What tools or references are allowed?
6. When should I stop and ask for approval?

If the skill answers these questions clearly, the agent becomes more reliable.

Final Thoughts

The future of agentic automation will not be built only with bigger models.

Better models matter, but enterprises also need better operating structure around those models.

They need:

reusable workflows
trusted context
clear tool boundaries
approval gates
consistent outputs
audit logs
security reviews
version control

That is why Skill files matter.

They give agents a repeatable way to perform specialized work. They turn tribal process knowledge into a reusable package. They help teams move from one-off prompts to governed agent workflows.

In my view, the Skill file is becoming one of the missing pieces in practical agent design.

Without it, an agent is smart but improvising.

With it, an agent starts to behave more like a trained digital worker that understands the process, follows the checklist, uses the right tools, and knows when to ask for help.

That is the real value of Skill files for agents.