Chapter 2 · Advanced Systems — Turn One-Time Wins Into a System

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.pptx

Only 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:

FolderWhat goes inWhen it is read
scripts/Executable scripts, such as format validators or batch processorsWhen execution needs them
references/Reference material, such as a glossary or style guideWhen something needs to be cited
templates/Output templates, such as PPTX or DOCX filesWhen 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:

  1. Click 【+】→【Choose skills】 in the composer and select the Skill to inspect; you can also type / to find it.
  2. Ask, for example: "Show me this Skill's SKILL.md and the material it references."
  3. 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:

LayerWhat gets loaded
Layer 1At 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 2When 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 3During 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:

LocationWhat to look for
descriptionApplicable tasks and trigger conditions
SKILL.mdInputs, execution steps, and output format
scriptsScripts and their required environment
references and templatesReference material and templates
External service configurationRequired services and authorization method

The Four Core Values of a Skill

ValueWhat it meansWhat you actually get
Procedural knowledgeWriting down "how we do things here"It stops guessing your table structures, field definitions, and approval habits
A locked workflowThe same class of task runs the same steps every timePredictable output, not one thing today and another tomorrow
Less repetitionWrite once, reuse long termYou stop reciting the same paragraph of requirements
An organisational assetIndividual experience becomes team capabilityOne 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.