Module 3 · Agent Tools, Knowledge, Memory & Research Design · scripted
Skills: The Brilliant Employee's First Day
Day one, zero context
Your new hire is brilliant — the strongest recruit you have ever made. Deep education, superb judgment, reads faster than anyone in the building. And this morning, at 09:00, they know nothing about your organization:
What the brilliant employee brings — and lacks
You know by now exactly who this is. It is every agent, in every conversation, forever — the amnesia never ends, so day one repeats each morning. The previous lessons built the pieces of the answer: training the agent can fetch, an index to navigate, a tree to bound the cost. Today those pieces get a package — the artifact a well-run organization has sitting on the desk before the employee arrives.
The standardized package
The package is called a skill, and its first virtue is not what's inside — it's that the container is standardized, and not just within your organization. Across organizations, across vendors, one format:
Why standardization is the superpower
The brilliant employee walks in ALREADY KNOWING how skills work — the way you walk into any new job already knowing how books, binders, and folders work. A known container costs nothing to learn. So the entire budget — tokens and attention — goes to the CONTENTS. Trained conventions are context you never pay for; a standard is a convention the whole world trained on.
Anatomy: SKILL.md is the root of a tree
A skill is a folder (shippable as a zip) with one conventional structure:
The anatomy — per the Agent Skills standard
The return value of this "tool" is LOADED CONTEXT.
One reading aid for the three directories: references/ is read, scripts/ is run, assets/ is used — knowledge for the agent's eyes, code for its hands, material for its work product.
And SKILL.md has exactly the design fork the previous lesson prepared you for:
Two kinds of SKILL.md
Either way: the wall only ever carries the walked path. The skill can be enormous; the bounded-wall guarantee holds.
How strict is the standard, really?
A practical note before we fill the package. The standard requires exactly one thing: SKILL.md. The three subdirectories are conventions, and in most tools and runtimes nothing enforces them — you can invent a directory of your own, point to it from SKILL.md, and the agent will usually discover it and use it just fine, because the agent navigates by reading, not by schema.
Convention, not contract
Guaranteed by the standard: SKILL.md — name, description,
instructions.
Convention, widely honored: references/ · scripts/ · assets/
Possible, not guaranteed: any directory you invent —
IF SKILL.md carries the map.
Stay standard when you can: the conventions are what the
employee already knows, and some tools DO treat them
specially. Deviate when you must — and when you do, SKILL.md
stops being a courtesy index and becomes the only map there is.The five things a skill can carry
1 · Instruction. The markdown chapters themselves — the mini-wiki above. Enough said; the previous lessons built this.
2 · Resources. Anything the job needs that isn't prose:
Resources — the desk, not just the manual
A resource answers: what does the employee need ON THE DESK — not explained, just THERE, findable and usable?
3 · Tools that travel. A skill can carry the code for its
tools — scripts/validate_report.py is just text, versioned with
the skill, executable wherever the skill lands. The skill doesn't
merely describe a capability; it ships it. (Tools unlocked by
connection, by errors, by search — and now delivered by package.
One planted question for later: code that travels and gets
executed — who audits it?)
4 · Examples. The neglected one — most skills are written as if examples hadn't been invented. But you know better: examples are extraordinarily information-dense training. Two completed expense reports teach the format better than three pages describing it; one worked edge case (the conference with the foreign per-diem) teaches the judgment:
Don't neglect the examples
Inline in SKILL.md for the short ones — a two-line
before/after, a filled-in format
As references/ files for full worked artifacts — a complete
report, a finished page, an edge case
with its resolution (the standard
files examples under references/)
If you would show a human trainee "here's one we did last
month" — and you would — put that in the skill.5 · Starting points. The most under-used facet of all: a skill can carry semi-complete work. Watch what it changes:
The same task, with and without a starting point
The starting-point principle
A template is a frozen 90% of the work. Don't make a mind rediscover what the organization already decided — ship the decisions as the starting file, and spend the intelligence on the 10% that is actually new.
The same move works one level up: a semi-complete application, a half-built analysis notebook, the report with every section headed and one filled in as a model. Anything your organization half-decides every time can be decided once and shipped.
The worked example, end to end
You have the following tools available for use:
- load_skill( name )
- ls
- read_file
- write_file
- run_command
Task: Build the landing page for the Molde pilot program — hero image from the shared drive, three sections: what, who, how to join.
Available skills:
- corporate-website — "Use when creating or modifying any public web page for the organization."
- expense-reports — "Use when filing, checking, or fixing expense reports."
⟨tool_use⟩
load_skill(name = "corporate-website")⟨tool_result⟩
Located at skills/corporate-website/. SKILL.md:
"1. ALWAYS start from assets/template/ — never from scratch.
2. Branding rules (short): references/branding-quickref.md
3. Approved images: the shared drive, /brand/approved/
4. Fill every {{placeholder}}; remove none.
5. Before shipping: run scripts/check_brand.py
6. Worked example: references/example-pilot-page.md"⟨tool_use⟩
run_command(cmd = "cp -r skills/corporate-website/assets/
template/ molde-pilot/")⟨tool_use⟩
read_file(path = "skills/corporate-website/references/
branding-quickref.md")⟨tool_result⟩
[12 lines: colors, tone ("plain, warm, no superlatives"),
logo rules, image style]⟨tool_use⟩
write_file(path = "molde-pilot/index.html", content = "[the
template with all seven placeholders filled — three sections,
hero from /brand/approved/]")⟨tool_use⟩
run_command(cmd = "python skills/corporate-website/scripts/
check_brand.py molde-pilot/")⟨tool_result⟩
PASS: colors ok · fonts ok · logo placement ok · alt-texts
present.The Molde pilot landing page is ready: built from the approved template, branding checked green. The hero image is from the approved brand library; text follows the house tone.
The catalog line
Which brings us to the highest-pressure words in the whole design. Most agents are given skills the way they're given tools: a list of names and descriptions, up front — and behind each description may stand an enormous package: hundreds of cases, dozens of files. That is the steepest compression ratio anywhere in the system: one line, standing for a world. Just as with tools, everything hangs on it — a skill with a vague description is a skill that is never loaded, and all its brilliance sleeps on disk.
And here the apple gets harder to use. A tool could often be named with one decompressing word — archive, refund — but a skill covers many situations at once, and no single word carries them. The proven pattern is different: describe by trigger, in the language of what the agent will be trying to do:
The catalog line — weak vs. strong
Why triggers work: "when you're trying to build an event page" carries rich context — the problem, the artifact, the process — in the agent's own terms. The description meets the agent at the moment of matching: task in hand, scanning lines.
Counter-examples earn their tokens in exactly two situations: when several skills are near neighbors and need disambiguating, and when you've watched a skill get loaded for the wrong jobs. Otherwise skip them — every catalog line rides every conversation, and this lesson's economics never sleep. Two more moves for hard cases: the top of SKILL.md itself can disambiguate — a first paragraph of "this skill is for X; for Y, use skill Z" that costs nothing until the skill is actually loaded — and yes, that means skills can refer to each other. Use it sparingly: references between skills are dependencies, and dependencies are how packages stop being portable.
One skill, many skills inside
A last design insight that the standard quietly permits. From the catalog's perspective, a skill is one entry — one name, one description, one package. But inside, SKILL.md is a tree root — and a tree can hold an entire family:
One catalog line, a whole department behind it
Four skills' worth of training, one standard package, one catalog line — and any given task walks exactly one branch. The agent navigating SKILL.md is doing the drill-down from the table-of-contents lesson; the skill is simply a tree with a name.
The packaging principle
A skill is one package by STANDARD and as many skills as its tree can hold by DESIGN. Bundle what belongs together; let SKILL.md route; and let each conversation pay for only the branch it walks.
You cannot stop the amnesia
Close where we opened. The brilliant employee will forget everything tonight, and tomorrow's task will find them newborn again. That cannot be fixed. What can be engineered is the desk:
The first day, packaged
You cannot stop the amnesia. You can only make the first day short. A skill is the first day, packaged: the manual, the index, the lookup tables, the tools, the worked examples, the half-built starting point — sitting on the desk before the employee exists.
- Rank the five facets for a task in your domain: which would save the most, and which does your field most neglect? (Bet: starting points.)
- Three lifetimes of instruction: the agent's base system message, SKILL.md, and the files behind SKILL.md. Give one rule for what belongs in each — and one example that's tempting to put in the wrong layer.