Module 3 · Agent Tools, Knowledge, Memory & Research Design · scripted
Skills: The Brilliant Employee's First Day
Overview
Here is the situation every agent conversation is born into, told as a story you already believe: the most brilliant hire you've ever made walks in knowing everything about the world and nothing about your organization — and must be productive today. We have the pieces of the answer: fetchable training, an index to navigate, a bounded tree. A skill is those pieces made into a standard package — day-one onboarding material a conversation can load when the task calls for it. In this lesson: the anatomy of the package, the one catalog line everything hangs on, and the discipline of writing for a reader whose day one repeats forever.
Where this fits
The skill is the package. Someone wrote the onboarding material down before the conversation existed — but the agent still has to find the skill in the catalog, read it, and explore the branches its task needs. How the skill is enabled is the dimension: usually the agent discovers it; a user-enabled skill arrives already provided.
Where this fits
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
| Brings | Lacks |
|---|---|
| languages, mathematics, writing, analysis, code — the trained skills of civilization | your policies |
| judgment — genuine, transferable judgment | your systems, and where they live |
| your formats and templates | |
| your history and decisions | |
| what "done" means HERE |
…and they must be productive TODAY.
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:
What a skill is
An agent skill is a standardized format for getting an agent up to speed in a new conversation.
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.
A complete skill, small enough to read
Before any general anatomy, here is an entire skill — four files. The job: handle sales-tax questions on orders.
A whole skill — four files
sales-tax/
├── SKILL.md ← the entry point (below)
├── references/
│ ├── vendor-policies.md ← knowledge, to read
│ └── state-tax-rates.csv ← data, to look up
└── scripts/
└── calculate-sales-tax.py ← code, to runAnd SKILL.md itself — the whole thing:
SKILL.md, in full
name: sales-tax description: Use when calculating or checking sales tax on an order or invoice. To handle a sales-tax task: 1. Check the vendor's rules first — exemptions and special cases: references/vendor-policies.md 2. Look up the current rate for the state: references/state-tax-rates.csv 3. Compute the tax by running: python scripts/calculate-sales-tax.py <order-file>
Read it once and the fit is clear: the instructions route, the reference explains, the data file is looked up, and the script does the arithmetic. Every skill — however large — is this pattern, grown.
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
expense-reports/ ← the skill
├── SKILL.md ← required. Front matter:
│ name + description (the
│ catalog line). Body: the
│ instructions — or the index
│ to them
├── references/ ← knowledge: policies, docs,
│ ├── travel-policy.md schemas — and examples
│ ├── per-diem-rates.csv
│ ├── example-report.md
│ └── example-edge-case.md
├── scripts/ ← executable code
│ └── validate_report.py
└── assets/ ← files used in the OUTPUT:
└── report-template.md templates, boilerplate,
brand files, sample data
Invoking a skill returns two things:
1. where the skill lives on disk
2. the contents of SKILL.md
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
| Simple skill | Complex skill |
|---|---|
| SKILL.md IS the training — compact, complete, done. | SKILL.md is a table of contents — a mini-wiki root. |
"To log an expense: 1. … 2. … 3. … Run scripts/validate before submitting." |
"1. Standard reports → references/standard.md · 2. Foreign travel → references/per-diem.md · 3. Formats: see examples/ · 4. Always validate: scripts/validate_report.py" |
Either way: the conversation only ever carries the walked path. The skill can be enormous; the bounded-cost 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
| Without | With |
|---|---|
| "Build the landing page." The agent starts from zero: picks libraries (unapproved), invents layout, rediscovers — or violates — the branding guidelines. Every conversation, every time, again. | assets/template/ contains the approved HTML, the sanctioned JS libraries, the CSS with branding baked in — and seven placeholders ({{page-title}}, {{hero-image}}, {{body-sections}}, …) plus fill-in instructions. |
| Rebuilds ~100% of the work, re-decides every decided question. | The task collapses from "build a website" to "fill in this one." |
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."
load_skill(name = "corporate-website")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"run_command(cmd = "cp -r skills/corporate-website/assets/
template/ molde-pilot/")Copied.read_file(path = "skills/corporate-website/references/
branding-quickref.md")[12 lines: colors, tone ("plain, warm, no superlatives"),
logo rules, image style]write_file(path = "molde-pilot/index.html", content = "[the
template with all seven placeholders filled — three sections,
hero from /brand/approved/]")OK. molde-pilot/index.html written.run_command(cmd = "python skills/corporate-website/scripts/
check_brand.py molde-pilot/")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
documents/ ← ONE skill in the catalog ├── SKILL.md │ "What are you producing? │ · Reports → references/reports.md │ · Slide decks → references/slides.md │ · Formal letters → references/letters.md │ · Spreadsheets → references/spreadsheets.md │ Templates for each: assets/templates/" ├── references/ reports.md · slides.md · letters.md · │ spreadsheets.md · example files for each ├── assets/ │ └── templates/ report.docx · deck.pptx · letter.docx └── scripts/ check_format.py 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.
Sketch the skill your research group would hand a brand-new brilliant employee. (1) Write the SKILL.md skeleton: the name, the catalog line, and the tree of files it points to. (2) For each of the things a skill can carry, note what yours carries — or why it doesn't need it. (3) Write the catalog line twice, weak and strong, and defend the strong one's trigger phrases. (4) Name the one mistake a skill-less agent would make on day one that this skill makes impossible.