2.2 Understanding a Skill: Structure, Progressive Disclosure, and Reuse Value
Lesson 1.5 covered what a Skill is, how to install it, and how to confirm it works. This lesson moves to the inside view and answers three questions:
How are its files organised? How does the agent actually load it? Why does that design matter?
Understanding those three pays off concretely: you locate problems faster, you use third-party Skills with more confidence, and you know when writing your own is the right move.
What a Skill Is: Definition and Boundaries
The AOS Work agent handles understanding tasks and organising execution. A Skill is a reusable set of instructions, scripts, references, and resources that tell the agent which tools to call for a class of task and what format to deliver.
Two boundaries are worth drawing first:
- A Skill is not a model. It changes no model parameters and raises no model capability ceiling. It changes how this work is done — codifying what you and your team already know.
- A Skill is not a prompt. A prompt describes this run; a Skill defines how this class of task is done. The full comparison is in 1.5.
What a Standard Skill Looks Like
The standard structure:
my-skill/
├── SKILL.md ← Required: the skill description
├── scripts/ ← Optional: executable scripts
│ └── check.py
├── references/ ← Optional: reference materials
│ └── guide.md
└── templates/ ← Optional: output templates
└── template.pptxOnly SKILL.md is required. The simplest Skill is a single Markdown file:
---
name: tech-article-writing
description: For writing about AI products, model reviews, and the tech industry. Use when a writing task is assigned.
---
When given a writing task:
1. Confirm the article's core angle.
2. Find primary sources.
3. Cross-check the key facts.
4. Produce a first draft in the user's writing style.
5. Check for banned phrasing and AI-sounding expressions.The name and description fields are metadata, and the description decides when this Skill gets selected. It is the single most important field in the file.
The three optional folders each have a job:
| Folder | What goes in | When it is read |
|---|---|---|
| scripts/ | Executable scripts, such as format validators or batch processors | When execution needs them |
| references/ | Reference material, such as a glossary or style guide | When something needs to be cited |
| templates/ | Output templates, such as PPTX or DOCX files | When producing deliverables |
For adding, enabling, and selecting a Skill in the composer, see AOS Work: Skill.
How to Look Inside a Skill
Before tuning, look at what it actually says. You do not need the file path — just ask the agent in the conversation:
- Click 【+】→【Choose skills】 in the composer and select the Skill to inspect; you can also type
/to find it. - Ask, for example: "Show me this Skill's SKILL.md and the material it references."
- The agent returns the real file contents: the instructions, the description field, and the scripts or references it uses.
Use the added report-review Skill named Report Review. First ask the agent to show its main instructions in SKILL.md, then request the referenced references/review-rules.md file to read the detailed review rules.
Progressive Disclosure: The Most Important Design Choice
The most important part of a Skill is not SKILL.md itself. It is progressive disclosure.
Say your agent has 20 Skills installed. It does not load all 20 in full into context at once — that would waste tokens and bury the model in irrelevant instructions.
The standard approach has three layers:
| Layer | What gets loaded |
|---|---|
| Layer 1 | At startup, the agent sees only each Skill's name and description — for example "pptx — handles PowerPoint creation, editing, and reading" and "pdf — handles PDF extraction, merging, and editing" |
| Layer 2 | When you say "write a product review article", it matches the description to the tech-article-writing Skill and only then loads the full SKILL.md |
| Layer 3 | During execution, if it needs to mimic your writing style it reads references/style.md; if it needs to check AI-sounding phrasing it runs scripts/check-ai-phrases.py |
Every Skill loads only tens to hundreds of metadata tokens at startup. Full instructions load when the Skill activates. Everything else loads on demand.
The payoff: you can install dozens or even hundreds of Skills with minimal impact on response time.
This mechanism solves a long-standing problem in the agent field: how do you give an agent a great deal of knowledge and method without loading all of it into the prompt forever?
Inspect a Skill's Dependencies
Open the Skill's description and files to see the resources it uses:
| Location | What to look for |
|---|---|
| description | Applicable tasks and trigger conditions |
| SKILL.md | Inputs, execution steps, and output format |
| scripts | Scripts and their required environment |
| references and templates | Reference material and templates |
| External service configuration | Required services and authorization method |
The Four Core Values of a Skill
| Value | What it means | What you actually get |
|---|---|---|
| Procedural knowledge | Writing down "how we do things here" | It stops guessing your table structures, field definitions, and approval habits |
| A locked workflow | The same class of task runs the same steps every time | Predictable output, not one thing today and another tomorrow |
| Less repetition | Write once, reuse long term | You stop reciting the same paragraph of requirements |
| An organisational asset | Individual experience becomes team capability | One person tunes a Skill; the whole group can use it |
The fourth is the most underrated. A Skill is a file, which means it can be copied, shared, and updated — the method you spent time tuning does not vanish when someone leaves, takes leave, or changes role.
Summary
Understanding a Skill's internal structure pays off concretely: you can locate problems, understand an existing Skill's dependencies, and know when to write your own.
Three lines cover this lesson: the description decides when it is selected, progressive disclosure decides how many you can install without slowing anything down, and its scripts and reference material decide the ceiling on what it can do.
Method is done. The next lesson is hands-on: building your first Skill.
2.1 Workspaces and Automation: Let the Work Continue
One-off tasks and ongoing work need different things. The second needs a place where context accumulates, not a longer conversation.
2.3 Creating a Skill: From One Success to a Reusable Method
Adding and using Skills was covered in 1.5. This section focuses on creating your own.