Understanding AI Agent Skills: Core Technology Explained (Chapter 4)

1. Historical Positioning of Agent Skills

1.1 Continuation of modular capability approaches

Before the open specification, the industry already had several mechanisms for modular AI capability extension:

Microsoft Bot Framework Skills

Semantic Kernel Skills (later renamed Plugins)

LangChain Toolkits

These mechanisms share the goal of packaging a capability for discovery, composition, and invocation by larger AI systems, but their encapsulated objects and runtime behaviours differ from today’s Agent Skills and are not natively compatible with the Agent Skills specification.

1.2 Anthropic turned Skill into a folder‑based specification

On 2025‑10‑16 Anthropic released Agent Skills and described a Skill as a folder that includes instructions, scripts, and resources that Claude can load when needed. On 2025‑12‑18 Anthropic published Agent Skills as an open standard to support skill portability across different Agent products. After the open‑standard release, products such as Claude, ChatGPT, Codex, Gemini CLI, VS Code, and GitHub Copilot began adopting Agent Skills, each with slightly different discovery paths, loading tools, and extension fields, but all generally follow the SKILL.md and progressive disclosure model.

2. What Is an Agent Skill

Agent Skill is a standardized way to package an Agent’s professional ability, experience, and execution logic into a reusable module.

From a filesystem perspective, a Skill is a directory. The recommended structure is:

my-skill/
├── SKILL.md          # required: YAML metadata + Markdown instructions
├── scripts/          # optional: executable code
├── references/       # optional: reference documents and domain knowledge
├── assets/           # optional: templates, images, data, etc.
└── ...               # optional: other files or directories

The only mandatory file is SKILL.md, which consists of two parts:

---
name: weekly-report
description: Analyze Jira, Confluence, and code‑commit records to generate a weekly report. Use when the user requests a summary of work progress, risks, and next‑week plans.
---

# Weekly Report

1. Collect work records within the specified time range.
2. Categorize by requirement, development, issue, and collaboration.
3. Identify risks, blockers, and pending information.
4. Use assets/weekly-report-template.docx to generate the final document.

2.1 Skill, Tool, and Prompt distinction

Prompt : how to ask the model to think or answer; contains instructions, context, output requirements.

Tool : actions the Agent can execute; functions, APIs, database queries, file operations.

Skill : when, why, and how to combine knowledge, processes, and tools to complete a class of tasks; includes operational guides, domain experience, scripts, references, templates.

A Skill can combine Tools and may embed Prompt‑style instructions; the body of SKILL.md becomes part of the model’s context, while scripts, references, and assets are read or executed on demand.

3. Why Agent Skills Appear

Assume a user asks: "Analyze my Jira, Confluence, and code‑commit records, then generate a weekly report."

3.1 Put all information and rules into the Prompt

Which Jira issues belong to the current cycle

Which Confluence documents need to be read

How to identify progress and risks

Which template to use for the report

When to ask the user for missing information

Problems of this approach: prompt length keeps growing, token consumption increases, rules become hard to maintain and version, reuse across agents or projects is difficult, and templates/scripts are hard to manage centrally.

3.2 Register only Tools

Tools such as:

read_jira
read_confluence
read_git_log

These Tools fetch data, but higher‑level questions remain: when to call which Tool, order of data fetching, how to know when enough information is gathered, how to handle conflicts or missing data, which situations need human confirmation, and what final format the output should follow.

3.3 Use Skill to encapsulate know‑how

Example Skill directory:

weekly-report/
├── SKILL.md
├── references/
│   ├── data-selection-rules.md
│   └── weekly-report-example.md
├── assets/
│   ├── weekly-report-template.docx
│   └── example.xlsx
└── scripts/
    └── analyze.py

SKILL.md

tells the Agent:

When to trigger this capability

Task boundaries

Step‑by‑step processing instructions

When to call the Jira, Confluence, and Git Tools

When to run analyze.py Which nodes need human confirmation

Which template and format to use for the final output

4. Composition of an Agent Skill

4.1 SKILL.md

Contains YAML front‑matter and a Markdown body. Required fields are name and description. Optional fields include license, compatibility, metadata, and allowed-tools (experimental).

Typical body sections:

Execution steps

Branching and decision conditions

Input and output examples

Common edge cases

Tool and script usage instructions

Failure handling and recovery methods

4.2 scripts/

Stores executable code for deterministic tasks such as data transformation, document parsing, format validation, batch file processing, and external system calls. Scripts are not necessarily loaded into the model context; the Agent can execute a script directly and return the result as a Tool Result.

4.3 references/

Holds on‑demand reading material, e.g., API specifications, domain terminology, business rules, example documents, error‑code explanations. SKILL.md must explicitly reference these files and indicate under which conditions they should be read.

4.4 assets/

Stores static resources that the Agent can use directly, such as Word/Excel/PowerPoint templates, images and charts, configuration files, JSON/YAML schemas, and sample data.

4.5 Enterprise‑grade Skill Design Checklist

Trigger : name, description, when‑to‑use, examples – tells the Agent when to load the Skill.

Scope : in‑scope, out‑of‑scope, fallback – defines capability boundaries.

Routing : scenario detection, branch decisions – selects execution path based on user intent.

Workflow : SOP, execution steps, termination conditions – standardises the task flow.

Tool Contract : tool, parameters, permissions, call constraints – ensures correct and safe tool usage.

Context : reference, template, knowledge – provides required context for reasoning.

Human‑in‑the‑loop : ask human, confirmation, evidence – allows human participation at critical decisions.

Output Contract : artifact, format, schema – guarantees standardised, reusable output.

Error Recovery : retry, fallback, recovery – provides failure‑recovery capability.

Evaluation : eval case, metrics, feedback – supports continuous evaluation and optimisation.

5. Execution Mechanism of Agent Skills

Agent Skills are executed via progressive disclosure: only the metadata needed for the current task is loaded first, and deeper content is fetched on demand.

In a Claude‑tap observation, the available Skill list appears in the system prompt as a system‑reminder and hints the model to use a Skill tool. Other clients may use file‑reading tools, activate_skill, load_skill, or other internal mechanisms.

5.1 Level 1: Discover Metadata

When the Agent starts or builds the request context, it scans available Skills and reads at least the name and description. Some implementations also load the Skill path, source, skillId, compatibility information, and custom metadata. At this point the full SKILL.md body is usually not yet in the context.

5.2 Level 2: Model Chooses a Skill

The model decides whether a Skill matches the current task based on the user request, the names and descriptions of currently available Skills, the system prompt, and the conversation context. If a Skill matches, the client loads it via a mechanism such as:

Skill(skill="pdf")
load_skill("sales-analytics")
read_file("skills/pdf/SKILL.md")
activate_skill("pdf")
load_skill_through_path(skillId="pdf_workspace", path="SKILL.md")

The goal of any of these calls is to inject the full Skill instructions into the current session context.

5.3 Level 3: On‑Demand Resource Loading

After SKILL.md is loaded, the Agent follows the instructions to decide whether to read additional resources:

Read a file from references/ Read or copy a file from assets/ Execute a script from scripts/ Call an external Tool or API

Only the resources actually used are fetched or executed; the rest remain untouched.

5.4 Agent Tool‑Calling Loop

Model decides
↓
Tool call
↓
Tool result added to context
↓
Model decides again, may call another tool or produce final output

The final result can be a document, a code snippet, a data analysis, or an external system operation.

6. Classification of Skills from a Product Perspective

6.1 Step‑Clarity

Explicit steps : workflow can be predefined (e.g., image compression, Excel cleaning, refund rule evaluation).

Open steps : goal is clear but the exact path is decided by the Agent at runtime (e.g., technical research, codebase exploration, market information gathering).

6.2 Impact & Irreversibility

Low impact, recoverable : trial‑and‑error is allowed.

High impact, hard to recover : may affect finance, compliance, privacy, brand, or external systems and thus require strict risk control.

Combining the two dimensions yields four typical Skill categories:

Automated workflow Skill (explicit steps, low impact)

Exploratory Skill (open steps, low impact)

Controlled workflow Skill (explicit steps, high impact)

Decision‑support Skill (open steps, high impact)

6.3 Automated Workflow Skill

Features: explicit steps, low impact. Examples: image compression, Excel‑to‑CSV conversion, file renaming, Markdown formatting. Control methods include input validation, output validation, repeatability, and retry mechanisms.

6.4 Controlled Workflow Skill

Features: explicit steps, high impact. Example: a refund Skill with a predefined flow that includes risk checks, amount calculations, and possible human review. Control methods include deterministic business rules, idempotent control, permission checks, human approval, audit logging, and compensation/rollback mechanisms.

6.5 Exploratory Skill

Features: open steps, low impact. Examples: technical research, codebase exploration, market information collection, creative brainstorming. The Skill should provide expert methods, available tools, information‑filtering criteria, evidence requirements, output structure, and stop conditions.

6.6 Decision‑Support Skill

Features: open steps, high impact. Example: investment analysis that involves financial data analysis, industry trend research, risk modelling, data verification, scenario comparison, and recommendation generation. Control methods include multi‑source evidence verification, data freshness checks, separation of facts/hypotheses/judgements, uncertainty presentation, restriction of automatic execution, and final human decision.

7. Technical Implementation of Agent Skills

Different Agent frameworks implement Skill handling differently, but a generic model can be described as:

Skill Repository
↓
Discovery, merging, and permission filtering
↓
Build the visible Skill Catalog for the current call
↓
Inject Skill metadata into the model context
↓
Model selects a Skill
↓
Load the Skill body via a loading tool or file‑reading tool
↓
On‑demand read resources, execute scripts, and call Tools

The model must answer three questions:

When to inject Skill metadata into the model context?

How does the model load the Skill body?

In a multi‑user environment, how to guarantee isolation of private Skills?

7.1 Q1 – When to Load Metadata

Client products often load Skill metadata at session start. Server‑side Agent frameworks usually recompute visible Skills before each model call based on the current user, tenant, environment, and permissions.

Typical pseudo‑code (Java style):

String systemPrompt = "You are an AI assistant…";
for (Middleware middleware : middlewares) {
    systemPrompt = middleware.onSystemPrompt(agent, runtimeContext, systemPrompt);
}

The resulting system prompt may contain XML‑style skill listings, for example:

<available_skills>
    <skill>
        <name>sql-optimization</name>
        <description>Write and optimise SQL queries</description>
        <skill-id>sql-optimization_workspace</skill-id>
    </skill>
</available_skills>

Recomputing per request (instead of permanent caching) brings benefits: immediate effect of permission changes, per‑user private Skill isolation, dynamic activation of gray‑release, environment, and organisational policies, and prompt discovery of newly added or updated Skills.

7.2 Q2 – How Does the Model Load the Skill Body

Loading method depends on the framework. Summary of implementations:

LangChain Deep Agents : SkillsMiddleware injects metadata; generic read_file reads SKILL.md.

LangChain Skill Tutorial : custom middleware injects metadata; custom load_skill tool.

AgentScope Java Harness : HarnessSkillMiddleware builds and injects a Catalog; load_skill_through_path tool.

Gemini CLI : discovery at startup; activate_skill tool.

A typical loading tool performs the following steps:

Obtain the visible SkillCatalog from the current runtime context.

Find the Skill by skillId.

If the path points to SKILL.md, return the full instruction body.

If the path points to references/, scripts/, or assets/, locate the resource inside the Skill directory.

Return the content as a Tool Result, which is added to the next model round.

7.3 Q3 – Skill Isolation in Multi‑User Environments

Multi‑tenant isolation cannot rely solely on system prompts. Even if a Skill is absent from the prompt, the loading tool must re‑check authorisation.

Recommended isolation flow:

User identity & tenant info
↓
Query Skill Repository with RuntimeContext
↓
Visibility & policy filtering
↓
Build the current call’s SkillCatalog
↓
Bind Catalog to RuntimeContext
↓
Loading tool queries only the current Catalog
↓
Resource paths are limited to the corresponding Skill root directory

Java‑style pseudo‑code:

// Before each request
List<AgentSkill> candidates = repository.getAllSkills(runtimeContext);
List<AgentSkill> visible = visibilityFilter.filter(candidates, runtimeContext);
SkillCatalog catalog = SkillCatalog.of(visible);
runtimeContext.put(SkillCatalog.class, catalog);

// When the model calls the loading tool
SkillCatalog currentCatalog = runtimeContext.get(SkillCatalog.class);
AgentSkill skill = currentCatalog.find(skillId);
if (skill == null) {
    throw new SkillNotFoundOrUnauthorizedException(skillId);
}

This ensures that both the system prompt and the loading tool draw from the same per‑request Catalog, preventing concurrent sessions from overwriting each other’s Skill views.

8. Engineering Practices, Boundaries, and Considerations

8.1 Skill Cannot Replace a Tool

A Skill can describe how to call an API, but it does not grant the API permission. Actions such as reading a database, sending a message, or modifying an order must still be performed via a Tool, MCP server, or other runtime capability.

8.2 Skill Cannot Replace Deterministic Workflows

For highly compliant, transactional, or state‑machine processes, the model should not be the sole executor of textual steps. Critical rules must be validated by program code, and state transitions should be controlled by a workflow engine or business system.

In this division, Skill is responsible for:

Understanding user intent

Selecting the workflow entry point

Collecting and organising information

Invoking deterministic capabilities

Explaining the results

8.3 Skill Does Not Replace RAG or Knowledge Bases

references/

is suitable for limited, task‑specific material. Large‑scale, continuously updated knowledge is still better served by search, Retrieval‑Augmented Generation, or external knowledge bases. Skills can specify how to query a knowledge base without embedding the entire knowledge set.

8.4 Too Many Skills Reduce Selection Accuracy

Even though metadata is more token‑efficient than full bodies, each Skill’s name and description still consume tokens. When many Skills have similar descriptions, the model may select the wrong Skill, load too many Skills simultaneously, or be unable to decide which Skill to prioritise.

Mitigation strategies:

Make description explicitly state capability content and applicable scenarios.

Merge highly overlapping Skills.

Use clear, mutually exclusive trigger conditions.

Filter unrelated Skills based on user and environment.

Establish an evaluation set for Skill selection.

8.5 Scripts in Skills Are a Supply‑Chain Risk

Installing a Skill may introduce Prompt text, executable code, and external dependencies. Before using a third‑party Skill, verify:

What the script does

Network endpoints it contacts

File‑system permissions required

Environment variables and credential usage

Source of dependent packages

Whether it contains prompt injection or privilege‑escalation commands

High‑risk environments should run scripts in sandboxes and retain approval and audit logs.

8.6 Skills Require Continuous Evaluation

Successful loading only proves that the runtime can discover and read a Skill. Reliability also requires assessment of:

Correct triggering on appropriate requests

Absence of false‑positive triggers

Adherence to task boundaries

Correct ordering of Tool calls

Graceful handling of missing information and exceptions

Output conforming to the required format

Proper activation of human confirmation for high‑risk nodes

9. Conclusion

Agent Skills extend the modular capability ideas of earlier frameworks and standardise a folder‑based, progressive‑disclosure model for AI Agents. Their value lies in:

Tools provide actionable capability; Skills provide the know‑how, process, and resources for using those tools.

Progressive disclosure avoids stuffing all content into the Prompt. SKILL.md is the entry point; scripts/, references/, and assets/ are on‑demand resources.

Different Agents may implement discovery and loading differently; load_skill is a common concept but not a fixed protocol.

In enterprise settings, constructing a per‑request visible Catalog and re‑authorising at load time is essential for multi‑tenant isolation.

The higher the risk, the more deterministic rules, permission checks, evidence verification, human confirmation, and audit are required.

From an engineering perspective, a Skill is a reusable module that packages professional expertise and task flow in the filesystem, with the Agent Runtime handling discovery, selection, loading, authorisation, and execution.

References

Anthropic: Introducing Agent Skills

Anthropic: Equipping agents for the real world with Agent Skills

Agent Skills Specification

OpenAI: Build skills

Gemini CLI: Agent Skills

VS Code: Use Agent Skills in VS Code

LangChain Deep Agents: Skills

LangChain: Skills architecture

Microsoft Semantic Kernel: Plugins

Microsoft Bot Framework: Implement a skill