跪拜 Guibai
← Back to the summary

AI Agent Skills Explained: The Folder Standard That Cuts Context Bloat

Hello everyone, I'm Ouyou. This article will share how to understand what AI Agent Skills are from 0 to 1—including what they really are, why they save a lot of context, the two types, and how beginners can select and install Skills written by others.

When we usually use AI Agents to write code or handle daily work, we most easily encounter two pain points:

First, every time we do the same kind of thing, we have to repeatedly describe a long string of content, having to copy and paste long prompts into the input box over and over; second, the distribution of 'AI Agent usage postures'—when others want to learn how I use AI Agents, or want to learn my prompts and working methods, just sending a few scattered pieces of text makes it hard for them to directly use it and get the same results.

Skills solve these two pain points. They can save the working methods you repeatedly execute, and they are also a very suitable carrier for packaging and distributing 'AI Agent usage postures'.

What is a Skill?

Many people, when first hearing about Skills, assume it's a complex proprietary plugin system.

Actually, from an official background, Skills (Agent Skills) were first launched and open-sourced by Anthropic (the company behind Claude) as an open specification, initially implemented in Claude and Claude Code. But after this specification was released, it quickly became no longer limited to Claude alone. Mainstream AI Agent tools like OpenAI's Codex, Cursor, DeepSeek Harness, etc., have all successively supported the same structure.

Why can a specification launched by one company quickly become a standard common to all AI Agents? Because the essence of a Skill is actually a few files; it is just a folder with a constrained specification.

Current AI Agents already have the ability to read files, write files, and can also execute terminal commands and call scripts themselves. Since Agents can read local files on their own, we don't need to copy a large string of prompts and paste them into the input box every time; and precisely because it's a folder, besides the documentation for AI to read (SKILL.md), you can also put scripts, reference files, and similar things.

It doesn't depend on platform-specific private interfaces. As long as you place files in a folder according to this agreed directory specification, any AI Agent that can read files can directly understand and execute it—once you write a Skill, you can reuse it directly across different Agents.

Why not stuff everything into the context directly?

Knowing that Agents can read files themselves, many people will then ask: why not just write all requirements and specifications into the project's global rules file (like AGENTS.md or CLAUDE.md, which are placed in the project root and fully read by default in every conversation), so the Agent carries them every time? Why make it a separate Skill?

This is because Skills have a progressive loading mechanism.

Comparison between stuffing a large amount of irrelevant context at once and Skills loading progressively like consulting a dictionary

Global rules files are suitable only for 'basic conventions that must be followed every time you work' (such as the project's tech stack, build commands, or code taboos). If we directly inject long specifications for all specific tasks into the AI Agent's context, a large portion of that content is likely unrelated to the task currently being performed.

For example, if today you just want to modify a backend API, and the context simultaneously contains tens of thousands of words of UI design specifications, copy-polishing standards, and video editing workflows, the inflated context not only increases the Token cost (the model's capacity and billing unit for processing text), but also degrades execution—because models have attention mechanisms, and too much irrelevant information scatters their attention.

With Skills, we can consult like a dictionary: first look at the table of contents, then according to the index, match to the specific content. This way we feed the model as little context as possible.

Breaking down a standard Skill folder

Following the idea of 'look at the table of contents first, then flip to the main text, finally use tools as needed', the following diagram shows the actual syntax structure in the SKILL.md file and the three-layer on-demand loading relationship of a standard Skill folder:

Visual comparison of the internal syntax structure of SKILL.md and the three-layer progressive loading of a standard Skill folder

A standard Skill folder usually looks like this:

my-skill/
├── SKILL.md        # Required entry: top has catalog index, below has main execution workflow
├── scripts/        # Optional: place fixed executable scripts
├── references/     # Optional: place detailed reference specs or long documents
└── assets/         # Optional: place page templates, images, and other static assets

A folder must have a SKILL.md as the entry point, with three optional subdirectories, working in three layers:

  1. The first layer is the 'dictionary catalog' (the metadata at the top of SKILL.md): at the very beginning of SKILL.md there is a small section of metadata wrapped in --- (YAML frontmatter), containing the Skill's name (name) and trigger description (description). When an Agent handles requests normally, the context window only always loads the name and description of all Skills, using them to decide whether to use this Skill this time.
  2. The second layer is the 'main text explanation' (the body of SKILL.md): only when your need matches the description in the catalog does the Agent actually open and read the body of SKILL.md, understanding the goal, judgment criteria, and execution steps of the task.
  3. The third layer is 'on-demand attachments' (scripts/, references/, and assets/): resources outside the main text are by default not loaded into context; they are only called when a specific step needs them:
    • scripts/ for executable scripts, to solidify repetitive, stable operations into programs;
    • references/ for long reference files (like detailed specifications needed only in one step of a workflow), which the Agent reads when necessary;
    • assets/ for templates or static assets (like HTML preview templates that open in the browser once data is filled in).

To give you an intuitive idea, a real SKILL.md is actually very direct; the core structure is just these lines:

---
name: my-ui-helper
description: Design and optimize web UI interfaces. Use when the user asks to explore visual directions, generate side-by-side comparison mockups, or modify styles against actual screenshots. Do not use for pure backend interface development.
---

## Execution Steps

1. First confirm the page goal with the user, give 3 design directions with different compositions.
2. When needing to generate a side-by-side comparison page, directly run `scripts/build-compare.mjs`, don't hand-write merge code each time.
3. When needing to check layout details, read the check items in `references/layout-checklist.md`.

It can be seen that the common purpose of this layered structure is to leave complex preparation work at the time of creating the Skill, so that the Agent maintains the leanest, clearest context in daily use.

Knowledge-based and Process-based Skills

In my view, all Skills can be divided into two types: knowledge-based Skills and process-based Skills.

1. Knowledge-based Skills: Supplement the judgment criteria the Agent doesn't have

Models aren't omniscient. For many tasks, if you let them do it directly, they only use their default habits. For example, asking AI to write Chinese copy often results in stacking modifiers, fabricating metaphors, or producing stiff translation-speak; or asking it to dissect a viral video often misses the core.

Knowledge-based Skill: Writing personal experience, aesthetics, and clear judgment criteria into documentation to correct the model's default cliché habits

At this point, you can write your own experience, aesthetics, and judgment criteria into a knowledge-based Skill, letting the Agent read this methodology before acting.

Take my open-sourced style specification Skill oil-tone as an example; it's a typical knowledge-based Skill: it has no complex external programs, its core is to tell the Agent how to write Chinese and English copy naturally, readable, fluent, and clear—for example, arranging paragraph order based on what the reader already knows, retaining function words like '的' and '了' that make the tone natural, and removing empty words without information. With this set of clear judgment criteria, the model no longer randomly adds rhetoric based on default habits.

2. Process-based Skills: Solidifying multi-step workflows and supporting scripts

The other type is repetitive workflows executed daily or frequently: what to do first, what to do next, what tools to use in between, and how to finally check and deliver. If you re-describe this with a large paragraph every time, the cost is very high. Such tasks are suitable for solidifying into process-based Skills.

Process-based Skill: Solidifying multi-step workflows and supporting scripts so the Agent runs the whole chain stably

Take my open-sourced UI design Skill Oil UI as an example; it represents a process-based Skill: it not only specifies the complete steps from "first expand composition differences to explore directions → prepare materials → implement in code → independently review with the image → finally do visual subtraction," but also directly provides supporting scripts in the folder, letting the Agent stably run the entire design chain step by step.

3. How to choose between global rules, quick prompts, and Skills?

After distinguishing knowledge-based and process-based types, we can clearly place the three common configuration methods in their proper positions in daily AI Agent use:

Finding, installing, and using Skills

For readers just starting out, if you want to try Skills written by others, we'll clearly explain step by step: "where to find and how to install → how to trigger after installation → principles to avoid pitfalls when selecting."

Three-step flow: finding ready-made Skills from GitHub, dropping a link for the Agent to auto-install, to automatic matching and slash invocation

1. Where to find them and three installation methods

The most direct place to find ready-made open-source Skills is GitHub, or some existing Skill repositories and aggregation sites (like SkillHub, skills.sh, SkillsMP, ClawHub, etc.). Code is files, Skills are also files, and both can be hosted and downloaded in the same form.

Since a Skill is just a folder, installing it essentially means placing that folder in the fixed directory the Agent reads on your computer. If you want it usable across all projects, put it in your personal global directory (e.g., Codex is ~/.codex/skills, Claude Code is ~/.claude/skills); if you only want it in the current project or share with the team, you can also put it in the .agents/skills (or .claude/skills) directory inside the project repo. In the path, ~ represents the current user's home directory, and folders starting with . are hidden by default in the system.

Usually there are three installation methods:

  1. Manual download and extraction: Download the repository archive from GitHub, extract it, and directly place it into the corresponding skills folder;
  2. Command-line installation: If Node.js is installed on your computer, you can run the community's npx skills add command in the terminal (followed by the GitHub username and repo name), then follow the prompts to select the Agent to install to:
    npx skills add oil-oil/oil-tone
    
  3. Have the AI Agent install it for you (recommended): Most of the time we don't need to find hidden directories or configure command-line environments ourselves. Because Agents can execute commands, download files, and create folders, they know best where their Skill directories are. You just send the repository URL to it and say:

    Help me download the Skill from this address, install it to the corresponding directory, and then check whether it can be read.

2. How to trigger and use Skills

How to trigger after installation? There are two ways: automatic matching and manual specification.

3. Core principle: don't use them before you encounter a problem; be wary of vague generic Skills

When selecting and installing third-party Skills from the community, there is a very important principle: If you haven't encountered a specific problem yourself, try not to install Skills; and it's certainly not true that more Skills are better.

Many newcomers to Skills like to install dozens at once from aggregation sites, thinking that since they load progressively, having a few extra standby is harmless. But there are two big problems:

Stay lean, and introduce Skills specifically when you hit a real pain point. When you find yourself repeating something daily, or when your experience is worth packaging and sharing with others, then you can start writing your own Skill—in the next article, we'll break down how to write a good product-level Skill from 0 to 1.


This article is adapted from Ouyou's (Oil Ouyou) "Oil Book" AI practical notes series.