A4.2 · LESSON 2 OF 6

A skill directory

Write a scoped skill package and manage its instructions and references within a task's context budget.

THE IDEA

A skill directory

In the Agent Skills format a skill is a directory containing at least a SKILL.md: YAML frontmatter with a required name and description, followed by instructions in Markdown. It may also hold scripts/, references/ and assets/. The name uses 1 to 64 lowercase letters, digits and single hyphens, with no leading or trailing hyphen, and matches the directory name. The description (up to 1024 characters) should say both what the skill does and when to use it, because that is what the agent matches against.

name

description

pdf-processing/ ├── SKILL.md required: frontmatter (name, description) + instructions ├── scripts/ optional: executable code ├── references/ optional: documentation loaded on demand └── assets/ optional: templates and static resources name rules (1–64 chars, lowercase letters, digits, single hyphens, must match the folder): ok description (1–1024 chars): ok, 67 chars says when to use it: yes

A skill needs a purpose, a concrete activation scope and a procedure. A folder of unrelated notes defines none of these.

Edit the name and description and watch the checks.

Predict first. Is a folder of unrelated notes enough to define a reliable skill workflow?

Chapter context

A skill packages reusable task instructions and optional supporting material. Context engineering decides which instructions and evidence are available for a particular operation. Loading more text is not automatically better than selecting the right text.

TRY IT YOURSELF

Part 1. Do it hands-on

Judge names by hand, then write a validator for a skill directory.

name

description

A skill needs a purpose, a concrete activation scope and a procedure. A folder of unrelated notes defines none of these.

"pdf-processing" (valid/invalid) "PDF-Processing" "pdf--processing" unrelated notes define a skill? (yes/no)

To do: Is the skill name "pdf-processing" valid under the Agent Skills rules (lowercase letters, digits and single hyphens; no leading or trailing hyphen; at most 64 characters)? Type valid or invalid
To do: "PDF-Processing"?
To do: "pdf--processing"?
To do: Is a folder of unrelated notes enough to define a reliable skill workflow? Type yes or no

Part 2. Do it in code

name_problems(name): a list in this order: "length" if the name is empty or longer than 64 characters; "characters" if it contains anything other than lowercase letters, digits and hyphens; "edge_hyphen" if it starts or ends with a hyphen; "double_hyphen" if it contains two hyphens in a row.
parse_frontmatter(text): the text starts with a line "---", then top-level "key: value" lines (indented lines are ignored), then a line "---". Return the dict (values stripped, surrounding quotes removed). ValueError if there is no frontmatter block.
validate_skill(dirname, files): files maps paths to contents. Problems, in order: "no_skill_md" if SKILL.md is absent (stop there); then "name_missing" or the name problems prefixed with "name:"; "name_dir_mismatch" if the name differs from dirname; "description_missing", or "description_too_long" above 1024 characters; "compatibility_too_long" above 500 characters.
describes_when(description): True if the description says when to use the skill — it contains "use when" or "when " (case-insensitive).

def name_problems(name):
    pass

def parse_frontmatter(text):
    pass

def validate_skill(dirname, files):
    pass

def describes_when(description):
    pass

Ctrl/⌘ + Enter runs it

Stuck, or something not working? You can come back to it any time.

CHECK YOUR UNDERSTANDING

Is a folder of unrelated notes enough to define a reliable skill workflow?

AYesBNo

Chapter reference: math, worked example & code

This section belongs to the whole chapter, so it is the same on every lesson in it and may cover a different lesson's topic. The code for the experiment you just ran is inside the experiment itself.

Math and notation

For a synthetic combined budget W, a bookkeeping model is available = W − instructions − history − tool results − reserved output. Actual provider contracts can separate these limits, so use the chosen model's documented accounting when implementing.

Worked example

A synthetic 8192-token budget reserves 1200 for instructions, 2800 for history, 1600 for tool results and 1500 for output. Remaining space is 1092 tokens. A 900-token skill body fits under this model; adding a 2000-token reference does not. The remedy is to select or retrieve the relevant passage rather than silently dropping task constraints.

Reference code

The following example uses the Python standard library and does not call a remote service.

window=8192
used=1200+2800+1600+1500
remaining=window-used
assert remaining == 1092
assert 900 <= remaining
assert 2000 > remaining

Python examples are provided for study and local execution; this page does not execute Python.

Common mistakes

Compaction can lose evidence and constraints. Skill installation is not task authorization. A context limit and a product's memory feature are different mechanisms.