AI Tools Field Guide

Open edition · no CAC needed

Advanced — Build with it

Skills files

Lesson 1 of 14≈5 min

A skill file is your shop's procedure for one job, written once, in a form the model loads only when the task matches. Write one, read somebody else's before trusting it, and see where it sits in the request the model receives.

Where a skill sits in the request

All of it, top to bottom, goes to the model as one text. It reads everything and continues from the end.

A skill is cheap until it loads: its one-line description is always in the window, its body only when the task matches.

  1. System rulesThe vendor, sometimes the DepartmentSent every turn; you never see them.
  2. AGENT.md or project instructionsWhoever built the helperThe standing instructions and persona.
  3. Skill descriptionsThe builder, or youOne line per installed skill, always present, so the model knows what it could load.
  4. The loaded skill (.md body)The builder, or youThe full procedure, loaded because the task matched its description. Paid for in tokens on every turn it stays loaded.
  5. Tool definitions and resultsThe harness and the toolsEvery tool it may call, and everything the tools returned.
  6. Your files and the conversationYou and the modelAttached documents and every earlier turn.
  7. Your messageYouThe only part you typed this turn.
A skill's body loads ahead of your message and is paid for in tokens on every turn it is loaded. Illustrative shares.

What a skill file is

A skill is a short document that tells the model how your office does one job: how a citation is written, how a read-ahead is laid out, how a weekly roll-up is assembled from the section inputs. It has two parts. A description of one or two lines says what the skill is for, and the harness reads only that part at the start of every session. The body holds the full procedure, and the harness loads it into the request only when your task matches the description. That is what makes it cheap. You pay for the long part only when you need it, and the model works from a procedure instead of guessing one.

The body lands in the preamble layer of the request, ahead of your message, alongside the system prompt and the tool list. If that sentence is new to you, read What you are actually sending first. Everything else on this page follows from it: a skill is text, the model reads it every time it is loaded, and a bad skill costs you tokens on every turn.

Today the same idea wears different names across products. The standing instructions in a Gemini Gem, a ChatGPT project or custom GPT, and a Grok playbook are all skill files with a form around them. The discipline below is what makes them behave; a wish list does not.

The anatomy

Part What it holds Why it earns its place
Name and description One line: the job and the trigger words ("Draft a personal award citation from a bio and a list of accomplishments") This is what the harness matches against. Vague here means the skill never loads, or loads for the wrong job.
When to use, when not Two or three bullets Stops the skill from being applied to a job that looks similar and is not
Inputs What you will hand it, in what form The model stops inventing the missing input
Steps The procedure, numbered, in the order a competent person does it Procedure beats adjectives. "Be concise" does nothing; "twelve lines, no line over 90 characters" does.
Output The exact format, with one filled-in example The example teaches the format better than any list of rules
Checks What "done" means: a checklist the model runs before it answers Turns "I think this is right" into a test
Limits What it must not do, and when to stop and ask Your escalation rule, written down once

An annotated example

The file below is a working shape, cut down. Comments in angle brackets are for you, not the model.

# Award citation drafter
Use when: asked to draft or tighten a personal award citation (NAM, NCM, MSM)
from a bio and a list of accomplishments. Not for evaluations or fitness reports.

## Inputs
- The member's name, rate or rank, and command.
- A list of accomplishments with dates and numbers.       <- no numbers, no citation
- The award level.

## Steps
1. Pull every accomplishment with a number, date, or named outcome.
2. Rank them by impact to the command, highest first.
3. Draft in the command's citation voice (see example). Past tense, no first person.
4. Keep to 12 lines of no more than 90 characters.        <- the form's box, measured
5. Run the checks. Fix, then answer.

## Output example
"For professional achievement in the superior performance of his duties while
serving as ... From June 2025 to May 2026, Petty Officer ... led 14 ..."       <- a real, approved one

## Checks
- Every number in the draft appears in the inputs.        <- the hallucination gate
- No line over 90 characters; no more than 12 lines.
- No PII beyond name, rank, command.                      <- the platform's rule, restated

## Limits
- If an accomplishment lacks a date or number, ask; do not invent one.
- Do not recommend an award level.

What is not in it matters too: no praise of the model, no "you are an expert", no paragraph about the importance of awards. Every line either changes the output or gates it.

Design rules that hold up

How a skill is stored, matched and installed

A skill is a plain text or markdown file. The first lines are its name and its description; everything under them is the body. There is no special syntax; the headings in the example are for people. Matching is done by the harness, not the model: at the start of a session it reads every skill's description, and when your request resembles one it loads that skill's body into the request. So the description is written for the matcher: the words a person would type, the job's name in your shop's language, and what it is not for. Installing depends on the product. In a chat product, the skill is the instruction box: paste the file into a Gem, a custom GPT, or a project's standing instructions, where it is loaded on every turn rather than matched. In vendor command-line tools it is a file in a skills folder that the tool scans, and other people's skills are installed by copying the file there. Wherever it lives, keep the master copy on your shop's drive with a date and an owner.

Loading a skill somebody else wrote

A skill is text that steers the model, which makes it the same class of thing as the instructions hidden in a document on the prompt injection page. Treat it that way.

  1. Read the whole file
  2. Check its examples against your command's forms
  3. See which tools it asks for
  4. Run it on three known inputs
  5. Compare with and without it

Five minutes, once, before it runs on real work.

The comparison is the step people skip. Give the model the same three inputs with the skill loaded and without, side by side. If the skill is doing its job the difference is obvious. If the outputs are the same, the skill is decoration and you should not pay for it. If the skilled output is worse, the skill needs rewriting.

Sharing one

A skill travels inside the thing that holds it: a shared project, or an agent published to named users or to your whole organization (Google help). Keep the source file itself on your shop's drive with a version line, so the next person can read it, and so the copy inside the agent can be replaced when the form changes. If nobody can read the skill, nobody can fix it.

What to do with this

Pick the one product your shop makes most often and dreads most. Find the best past example of it. Write the skill from that example this afternoon, and run the with-and-without comparison on three old inputs. Then read how the model gets abilities beyond text: Tools and function calling.

Vendor facts checked ; re-verify before relying on them.