Author an Agent Skill

---name: authoring-agent-skillsdescription: "Write a SKILL.md an agent will actually load and follow — trigger-shaped description, valid frontmatter, progressive disclosure, no credentials. Use when creating or reviewing a skill, packaging a repeated workflow, or deciding whether something should be a skill, a connector or just a prompt."license: MITmetadata:  title: "Author an Agent Skill"  version: 1.0.0  author: lobstack  category: authoring  tags: [authoring, skills, documentation]--- # Author an Agent Skill A skill is a folder with SKILL.md at its root that teaches an agent how to dosomething well. Markdown, plus optional scripts and reference files. Nocredentials, because there is nothing to authenticate against. The unit ofdistribution is text, so the copy *is* the install. ```my-skill/  SKILL.md            # required. frontmatter + instructions  reference/    schema.md         # read on demand, not on every turn  scripts/    check.py          # deterministic work the model should not do by hand``` ## Is it a skill at all? Three things get confused, and picking wrong wastes a week: | you want | build || --- | --- || the agent to *know how* to do something | a **skill** — markdown, no credentials, portable || the agent to *reach* a service | a **connector** — auth config, tool definitions, an endpoint || the agent to do one specific thing right now | a **prompt**. Not everything needs packaging | If your draft has an API key in it, you are writing a connector. If it is"summarise this in our house style, this once", it is a prompt. A skill earns itsfolder when it is knowledge that applies repeatedly, that a general model does notalready have, and that you would otherwise re-explain. ## The frontmatter is a contract ```yaml---name: lobstack-receiptsdescription: "Read the receipt Lobstack returns on every model call — cost_usd, savings_usd, baseline_reason — and report cost from it instead of estimating. Use when a response carries x_lobstack or an x-lobstack-* header, when asked what a call or a run cost, or when a cost renders as $0.00."license: MITmetadata:  version: 1.0.0  author: lobstack  tags: [cost, receipts, metering]---``` - `name` — lowercase, hyphenated, matches the directory. This is the handle.- `description` — the only thing that decides whether the skill ever fires.  See below; it is the whole game.- `license` — state one. A skill with no licence cannot be adopted by anyone  with a lawyer.- Everything else under `metadata`, which loaders tolerate and do not  interpret. Quote the description if it contains a colon. One unquoted colon is a YAML parseerror, which is a skill that silently never loads — and "silently" is the partthat costs you a day. ## The description is the trigger An agent decides whether to load a skill from its name and description alone. Itdoes not read the body first. So a description that only says *what* the skill iswill not fire at the moment it is needed. Write two halves: what it does, then when to use it, in the words that will bein the air when it applies. ```✗ "Utilities for cost analysis."✗ "Best practices for working with the Lobstack Gateway."✓ "Hold an agent inside a dollar budget using the per-call cost the Gateway   returns. Use when building an autonomous loop, when asked to cap spend on a   task, or when a Gateway call returns 402 Payment Required."``` Name the concrete triggers: the error code, the field name, the file type, thephrase a person would actually say. 402, x_lobstack, "what did this cost","route Cursor through". Those are what match. ## Write the body for an agent, not a reader - Imperative, specific, testable. "Set max_tokens" beats "consider limiting  output". The second is advice; the first is an instruction.- Lead with the rule, then the reason. An agent that stops reading after the  first paragraph should still be right.- Show the exact string. Real header names, real field names, real endpoint  paths, copy-pasteable commands. This is the single biggest difference between a  skill that changes behaviour and one that reads well.- Say what not to do, and why. Negative constraints are followed more reliably  than positive suggestions, and the "why" is what lets the agent generalise  rather than pattern-match.- One skill, one job. If the description needs "and", split it.- Keep `SKILL.md` short enough to be read whole — a few hundred lines. Long  tables, full schemas and rare edge cases go in reference/ and get read when  needed. Everything inline is paid for on every turn that loads the skill; see  cost-aware-system-prompts.- Push determinism into scripts. If the task is "validate this JSON" or "count  these rows", ship a script and tell the agent to run it. A model doing  arithmetic by hand is a model getting arithmetic wrong occasionally. ## Never put in a skill - Credentials, tokens, keys, or connection strings. Skills are copied, pasted  into repositories, and committed. Reference an environment variable by name.- Anything that goes stale silently — a price table, a model list, a rate card,  a version number of somebody else's software. Tell the agent which endpoint to  ask instead.- A claim you have not verified. A skill that confidently documents behaviour  the system does not have is a bug report written in advance and filed by your  user. Read the source, then write the sentence. ## Test it, or you have not written it 1. Does it load? Parse the frontmatter. A YAML error is silent.2. Does it fire? Start a fresh session, say the thing a user would say, and   check the skill was picked up without you naming it. If not, the description is   the problem, not the body.3. Does it change behaviour? Run the same task with and without it and diff the   result. A skill that changes nothing measurable should be deleted, however good   it reads.4. Does it survive a cheaper model? If it only works on a flagship, the   instructions are implicit somewhere. Make them explicit. ## Versioning and publishing Bump metadata.version when the *instructions* change, not when a typo is fixed.Keep the directory name stable — it is the handle people have written down. Statethe licence. Say what the skill assumes about the environment in the firstparagraph, because the reader's environment is not yours. Skills submitted to this archive keep their author and their licence. OfficialLobstack skills are MIT, and there are no install counts here because we have noneand inventing them would be the first false thing on the page.