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.
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:
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:
- The first layer is the 'dictionary catalog' (the metadata at the top of
SKILL.md): at the very beginning ofSKILL.mdthere 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 thenameanddescriptionof all Skills, using them to decide whether to use this Skill this time. - 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 ofSKILL.md, understanding the goal, judgment criteria, and execution steps of the task. - The third layer is 'on-demand attachments' (
scripts/,references/, andassets/): 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.
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.
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:
- Basic conventions that must be followed every time → put them in global rules (
AGENTS.md/CLAUDE.md): e.g., the project's tech stack, test commands, and directory structure. These are read persistently in every new window; just keep them short; - Daily reminders of just one or two sentences → save them as quick prompts: e.g., when troubleshooting, casually send a phrase like 'first locate the core problem and tell me in plain language, don't modify code directly yet'. Such common one- or two-sentence phrases are best saved as quick prompts; no need to build a Skill with a directory;
- Specialized capabilities containing specific practical judgment criteria or multi-step scripts → use Skills: only content that genuinely accumulates specific business experience (knowhow) or solidifies multi-step tool scripts has real value when made into an on-demand Skill.
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."
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:
- Manual download and extraction: Download the repository archive from GitHub, extract it, and directly place it into the corresponding
skillsfolder; - Command-line installation: If Node.js is installed on your computer, you can run the community's
npx skills addcommand 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 - 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.
- Automatic matching: You just state your need normally in the dialog (e.g., "help me make this text more natural and fluent"), and the Agent scans the
descriptionat the top of all installed Skills; when it matches, it automatically loads the body ofoil-toneto execute. - Manual specification or symbol invocation: If you want to explicitly use a particular Skill, you can name it directly in the sentence (e.g., "please use
oil-toneto polish this paragraph for me"), or type an invocation symbol in the input box to select it from a list (different Agents have slightly different symbols; for example, Claude Code commonly uses/, Codex supports$to invoke Skills; note that when typing/, the list usually also includes system commands like/clear,/compact, not just installed Skills).
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:
- First, broad, empty, or badly written Skills can lead the Agent astray. Many Skills in the community are generated by others directly asking AI to make them up out of thin air, without any specific practical experience (knowhow) — for example, only writing "you are a top designer" without any specific specifications or judgment criteria (just as making a Skill out of the multiplication table doesn't improve the model's math ability). The more generic and broader a Skill is, the less it helps specific tasks; if its instructions are chaotic and stiff, triggering it may even degrade otherwise normal execution.
- Second, installing too many still interferes with model decisions. Although the Skill body is only loaded after triggering, the
nameanddescriptionof all installed Skills are always in the context window. If you install a bunch of Skills with broad or overlapping functions, the model can easily get confused when matching needs about which to use when, again scattering attention.
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.