Agent Skills

Skills & connectors

Two things that get called by the same word and are not variants of one idea. One teaches an agent how to do something; the other grants it access to a service.

An Agent Skill is a folder with a SKILL.md at its root. Markdown, plus optional scripts and reference files. It teaches an agent how to do something well. It has no credentials, because there is nothing for it to authenticate against, and it works in any agent that reads a skills directory. The unit of distribution is text, so copying the file is the install.

A connector is a credentialed integration: an MCP server, plus the fields that server needs. It gives an agent access to a service. It is configured in Lob Bot, where its secrets are sealed into a vault on your own machine, and it is not copy-pasteable — pasting a Slack connector into a repository gives you a shape and no access.

This site called both of them skills until recently/skills rendered a catalogue of credentialed integrations, every one with a required-config block, and not one of them was an Agent Skill. That catalogue was the configuration for the agent-VM runtime and it has been deleted along with it. Connectors now describes what Lob Bot actually has: 13 that name a service, and 2 that take any MCP server you point them at. Agent Skills is the archive of 10 actual skills. If you followed an old link expecting Slack and GitHub, you want Connectors.

The difference, in a table

	Agent Skill	Connector
What it does	Teaches the agent how	Grants access to a service
What it is	SKILL.md	An MCP server plus the fields it needs
Credentials	None	API key or OAuth grant
Install	Copy the file	Authorise it in Lob Bot
Portable	Any agent that reads skills	No — it is your account
Versioned by	The file, in your repo	The MCP server it runs
Licence	MIT, for the official ones	Not applicable
Lives at	/skills	/connectors

The quickest test: if your draft has an API key in it, you are writing a connector. If it has no credentials and you would happily send it to a colleague as a file, it is a skill. And if it is "do this one specific thing right now", it is neither — it is a prompt, and not everything needs packaging.

Anatomy of a skill

The layouttext

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

Only SKILL.md is required, and for most skills it is the whole thing. The other two directories exist for progressive disclosure: anything long, conditional or rarely needed belongs in a file the agent reads when it needs it rather than inline, where it is paid for on every turn that loads the skill.

The frontmatter is a contract

SKILL.md, first linesyaml

---
name: lobstack-receipts
description: "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: MIT
metadata:
  version: 1.0.0
  author: lobstack
  tags: [cost, receipts, metering]
---

Key	Why it matters
name	Lowercase, hyphenated, matches the directory. The handle everything else refers to.
description	The only thing that decides whether the skill ever loads. See below.
license	State one. A skill with no licence cannot be adopted by anyone with a lawyer.
metadata	Everything else. Loaders tolerate it and do not interpret it.

Quote a description containing a colonOne unquoted colon is a YAML parse error, and a skill whose frontmatter does not parse silently never loads. Nothing tells you. Parse the file before you ship it.

The description is the trigger

An agent decides whether to load a skill from its name and description alone — it does not read the body first. So a description that only says what the skill is will not fire at the moment it is needed. Write two halves: what it does, then when to use it, in the words that will be in the air when it applies.

Three attempts at the same skilltext

✗  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 extension, the phrase a person would actually say. 402, x_lobstack, "what did this cost", "route Cursor through". Those are what match.

Writing the body

You are writing for an agent that will act on it, not for a reader who will admire it.

Imperative and specific. "Set max_tokens" beats "consider limiting output". The second is advice; the first is an instruction.
Rule first, reason second. An agent that stops reading after the first paragraph should still be right.
Show the exact string. Real header names, real field names, real paths, commands that run as written. 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 reason is what lets the agent generalise instead of pattern-matching.
One skill, one job. If the description needs an "and", split it.
Push determinism into scripts. A model doing arithmetic by hand is a model getting arithmetic wrong occasionally.

Never put in a skill:

Credentials. 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 version number of somebody else's software. Tell the agent which endpoint to ask.
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.

Testing one

1
Does it parse?
Load the frontmatter as YAML. A parse error is silent at runtime, which is the whole problem with it.
2
Does it fire?
Start a fresh session, say what a user would say, and check the skill was picked up without you naming it. If it was not, the description is wrong — 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 well it reads.
4
Does it survive a cheaper model?
If it only works on a flagship, an instruction is implicit somewhere. Make it explicit.

Installing one

The copy is the installbash

mkdir -p .claude/skills/lobstack-receipts
# paste SKILL.md into .claude/skills/lobstack-receipts/SKILL.md
# start a new session

The path shown is Claude Code's. Other agents differ in the parent directory only — the file is the same file, which is the property that makes skills worth distributing as text. Delete the folder to uninstall. There is no package, no registry client and no telemetry.

The archive

Agent Skills holds 10 skills, 10 of them written and maintained by Lobstack and licensed MIT. Each one's complete SKILL.md is on the page with a copy button, and each has its own URL at /skills/<name>.

The archive accepts skills from anyone. A submission keeps its author and its own licence, both shown on the card and in the frontmatter. What it must have: a SKILL.md that parses, a description saying when to use it, no credentials, and no claim that cannot be checked.

There are no install counts on that pageOther directories rank by installs. We have none, so ranking by them would mean inventing them — and a fabricated number would make everything beside it worth less. The archive orders by category and says how many lines each file is.