Skill Security Series - Skill Basics

Skill Security Series - Skill Basics

Preface

Before summarizing the risks associated with Skills, let’s first take a look at what a Skill is through this article to gain a basic understanding.

What is a Skill

Skill translates to “ability” or “technique”. In the AI domain, a Skill is exactly that—an ability. For example, if you want to give an Agent “Skill A”, you need to have a Skill for “Skill A”, which essentially empowers the Agent. The essence of a Skill is writing prompts into an md file for the Agent to call upon.

This prompt acts as our expertise. We document the workflow and experience of a task in an md file, essentially telling the Agent how to accomplish that task. At the same time, Skills also support script invocation—for example, specifying in the md file that when handling a specific detail, a certain script should be called, and placing the script in the corresponding directory.

What is a Skill Used For

To some extent, a Skill is equivalent to a workflow—similar to workflows in Dify or n8n. Some tasks can be handled with workflows, but Skills can also achieve the same results. Of course, not everything achievable with workflows can be implemented with Skills—this analogy is just for easier understanding.

So what are Skills useful for? They can be summarized in three points:

1. Eliminate Repetition: You don’t have to repeat the same instructions every time. For example, if you ask AI to write a weekly report, you might have format requirements, file type requirements for saving, tone requirements, etc. You’d need to specify these each time you write, and to ensure accuracy next week, you’d have to tell it again—repetitive and redundant. By turning these requirements into a Skill, you don’t need to explain them repeatedly—just invoke the Skill directly.

2. Centralized Updates: When a Skill needs updating, you don’t have to modify every place it’s used. For instance, if you use separate sessions for weekly reports to facilitate later review, but the storage format needs to change (e.g., from Excel to md), updating each session individually is tedious. With a Skill, you only need to modify the Skill content, and all related sessions automatically use the latest version.

3. Session Independence: If you start a new session, you’d normally have to re-explain all the weekly report requirements. But with a Skill, you can simply invoke it directly.

As you can see, Skills are ideal when you need unified requirements, repetitive actions, or frequent tasks. Note that if a tool can handle something (e.g., image format conversion, image compression), just use the tool—there’s no need to turn it into a Skill.

Additionally, a Skill should do only one thing. It’s not recommended to write multiple tasks into a single Skill—avoid creating a “universal” Skill, as it becomes difficult to maintain and optimize, and the Agent is more prone to errors.

Advantages of Skill

Skills have become popular because people have discovered many conveniences they offer:

1. Context Efficiency: Compared to traditional prompts that dump everything into the model and consume context space, Skills load content on demand.

2. External Workspace: Traditional prompts use a single chat context as the only workspace—all input, processing, and output information piles up in one chat box. Skills, on the other hand, make the file system the Agent’s external memory and workbench.

3. Collaborative Workflows: Traditional prompts handle individual tasks in isolation—one prompt doesn’t know what other prompts exist. Skills can build collaborative workflows where multiple Skills work together, each handling its own responsibilities, enabling more complex tasks.

4. Iteration and Maintenance: No matter how many sessions there are, all read rules from the SKILL.md file. Changes take effect globally, and files support version control for continuous iteration and optimization.

Skill Example

Let’s look at the basic structure of a Skill:

A Skill is a folder (named with lowercase letters and hyphens) containing a single SKILL.md file (SKILL in all caps). The basic structure of SKILL.md is as follows:

---
name: weekly-report
description: Generate weekly reports. Use when the user asks to write weekly reports, work summaries, or work updates.
---
Steps:
1. Confirm what tasks the user completed this week
2. Output in table format: Task | Progress | Notes
3. Use a friendly tone, like reporting work to a colleague
4. Save the file in Markdown format to the current directory

• name: The name of the Skill, consistent with the folder name.
• description: A brief description of what the Skill does and when to use it. The formula is: description = function definition + trigger scenario/keywords

The content between --- is metadata, called YAML front matter. When the Agent starts, it checks this metadata to determine which Skill to invoke. The content after --- is the Skill body, which specifies the steps, rules, and other details. The body is only loaded after it is determined which Skill to invoke.

The key is writing a good description—it must clearly describe the function and trigger scenarios. Otherwise, the Agent won’t know whether to invoke the Skill. When writing a Skill description, refer to the following rules:

A poor description may cause the Agent to fail to accurately identify the right Skill, loading the wrong one—wasting time and consuming tokens. It may also cause the Agent to fail to recognize the need entirely, thinking it can handle the request without a Skill, also wasting time and tokens.

1. Always follow the formula: description = function definition + trigger scenario/keywords
2. Avoid personal pronouns. Describe the function directly in declarative sentences. For example, “You can use this Skill to identify PDFs and generate statistical tables” should be written as “Identify PDFs and generate statistical tables.”
3. Keep the description concise—suggested length is 50–200 characters.
4. Use negative trigger words. When many Skills are installed, multiple Skills might be able to handle the same task. You can define boundaries in the description—i.e., when the Skill should NOT be triggered.

Also, before creating a Skill, make sure you are very familiar with the entire process. It’s hard to write a stable Skill otherwise. Before writing a Skill, confirm the following:

1. Problem: What problem needs to be solved
2. Scenario: Who uses it and when
3. Input: What information needs to be provided
4. Output: What the Skill needs to produce
5. Rules: What constraints apply
6. Prohibited List: What must absolutely not be done

On-Demand Loading

The on-demand loading mechanism of Skills is also called progressive disclosure:

• Load on Enable: When the Agent starts, it loads only the YAML front matter of all Skills. After the user sends an instruction, the model decides which Skill to use based on the instruction content.
• Load on Use: Once a specific Skill is chosen, the Agent loads the body content of that Skill and executes it.
• Load When Necessary: For complex Skills, there may be more than just a SKILL.md file. There could be associated files—reference documents in the references/ directory, Python scripts in scripts/, static resources like images and PDFs in assets/. These associated files are only loaded when triggered by a specific task—they are loaded only when necessary.

How to trigger them can be specified in SKILL.md. For example, “when XXX is needed, call scripts/test.py for processing.” When specifying paths, it’s recommended to use relative paths from the Skill root directory and only reference one level deep. Avoid nested references (A references B, B references C), as this can confuse the Agent and increase token overhead.

Difference from MCP

Several concepts are involved in Agents:

• Prompt: Instructions given by the user to the AI.
• Large Language Model: The Agent’s brain, responsible for thinking, reasoning, and issuing commands.
• Context: The collection of information the Agent processes when handling a task.
• Tool: Tools the Agent can call, such as built-in tools or extension tools.
• Skill: A specific task operation manual written for the Agent to read.
• MCP: A unified integration standard for connecting external tools to the Agent.

Skills and MCP are easily confused. To summarize: Skills tell the Agent how to do something, while MCP allows various external tools to connect to the Agent, enabling the Agent to call them.

Tips for Using Skills

1. Although the Agent only loads Skill metadata on startup, if there are too many Skills, they still consume context space. The official recommendation is to install 20–50 Skills. If the metadata is in Chinese, it takes up more space, so the number should be further reduced. Consider disabling unused Skills as needed.

   Also, use tiered management: put frequently used Skills in a global directory, and project-specific Skills in a project-level directory to prevent the Agent from loading all Skills on startup.

2. Keep the content length of SKILL.md under control. Split it up—put different functions into associated files. It’s recommended to keep it within 5,000 tokens (about 3,800 Chinese characters) to avoid consuming too much context.

3. Once a Skill is used, its content remains in the current session’s context. Using multiple complex Skills in succession takes up significant context space. Consider starting a new session when necessary.

Summary

In essence, a Skill is a way to package your own expertise—giving it to the Agent in the form of text and code for the Agent to call upon.

This concludes the Skill Security Series - Skill Basics. Thank you for reading.