Skills and instructions

An agent that brings a manifest can tell every agent that uses its container how to use it. Two manifest fields do this. instructions is a few lines of rules that nearly every MCP client receives when it connects. skill is a complete usage guide, a SKILL.md, that clients load when the task calls for it. Both are free to read, and both are shown word for word to the person approving the install. See Connecting agents for what that person sees.

What each field does

instructions reaches the agent at connect time, and skill reaches it on demand. A client that supports neither mechanism can still read the skill as an ordinary MCP resource.

Field	What a connecting agent gets	When	Limit
instructions	The MCP server instructions in the container’s initialize response. Most MCP clients add them to the agent’s context.	Every connection	16,000 characters
skill	A SKILL.md served over MCP’s Skills extension (io.modelcontextprotocol/skills) at skill://<name>/SKILL.md. Clients that support skills list it and load it when it’s relevant.	When the client or agent asks for it	64,000 characters

{
  "instructions": "Call search_places before save_place so you don't save a place twice. Read skill://someday/SKILL.md for the full guide.",
  "skill": "---\nname: someday\ndescription: Save places the user wants to go. Use when the user mentions a place.\n---\n\n# Someday\n\n..."
}

The example shows only these two fields. The rest of the format, including the app section (app.id, app.name, app.version, the format’s literal field names for your agent), is in the Wire SDK README.

Keep instructions short and the skill complete

Write instructions as the short rules and the skill as a guide that stands on its own. The two travel separately: a client that loads the skill may not show the instructions next to it, and a client that reads the instructions may never open the skill. So the instructions should hold the rules an agent can’t skip, such as which tool to call first, and point at the skill. The skill should repeat those rules and add everything else: what each tool is for, the order to call them in, and worked examples.

If the manifest has a skill and no instructions, the container sends one line built from the skill’s description that tells the agent to read the skill:

Save places the user wants to go. Use when the user mentions a place. Before using this container's tools, read the usage guide at skill://someday/SKILL.md (resources/read).

A container with no agent installed sends no instructions.

Write the skill as an Agent Skills SKILL.md

The skill is a SKILL.md in the Agent Skills format: YAML frontmatter, then a Markdown body. Wire checks it when you register the manifest and refuses one that a host might read differently.

---
name: someday
description: Save places the user wants to go. Use when the user mentions a place.
license: MIT
metadata:
  version: "1.1"
---

# Someday

Call `search_places` before `save_place`, so a place is never saved twice.
...

Frontmatter field	Required	Rule
name	Yes	1 to 64 lowercase letters, digits, and single hyphens, with no hyphen at the start or end.
description	Yes	What the skill does and when to use it, up to 1,024 characters.
license	No	Up to 500 characters.
compatibility	No	Up to 500 characters.
metadata	No	A map of strings: up to 64 keys, each value up to 1,024 characters.

The name is the skill’s directory. A skill named someday is served at skill://someday/SKILL.md, so the name in the frontmatter is the directory in the URI, and there is nothing else to configure.

A few rules keep the frontmatter unambiguous, so every host parses it the way Wire does:

• Any field not in the table is refused, and so is allowed-tools. A skill a container serves can’t pre-approve tools on the agent’s machine.
• Write each field on one line, plain or in quotes.
• Quote a value that would otherwise read as a number, true or false, or null, as in version: "1.1".
• Folded (>) and literal (|) blocks are refused.

The whole skill string, frontmatter and body, can be up to 64,000 characters.

How agents get the skill

A container with a skill declares the Skills extension when a client connects and answers skills/list, skills/get, and resources/read on the skill’s skill:// URI. The skill file also appears in resources/list, next to the container’s files.

• Digest-verified. Each listing carries the file’s sha256 digest and size, computed from the bytes a read returns. A host that supports skills can check that what it loaded is what was listed. The frontmatter in the listing is the file’s own.
• Loaded on demand. Hosts that support skills typically show the agent the name and description, and load the full file when the task matches. A listing may be cached by the client for up to a minute.
• Free. Listing or reading a skill isn’t a tool call or a file download, so it never costs credits.
• Part of the container’s setup, not its content. The skill isn’t stored as entries, so searching, exploring, or querying the container never returns it.

Changing the skill or the instructions

A registered version names one document. To change the skill or the instructions, register your manifest again with a higher app.version. Registering different content under a version that’s already registered is refused with VERSION_EXISTS.

A new version reaches a container when someone approves the update, through your agent’s connect flow or in the Wire dashboard (see Updates). Both screens say whether the skill or the instructions are added, changed, or removed, and show the new text. Until then, agents using that container keep getting the version it has installed. A new version without a skill removes the skill an earlier version added.

If your agent is verified, a version that changes only the skill or the instructions needs no approval. It is applied the next time the person uses your agent, and the container’s activity feed records the update. See Updates for a verified agent.

Existing installs need no action from anyone. An install made before containers served skills starts serving the skill and instructions of the version its user approved the next time the container is used, without reconnecting. A skill you add in a later version reaches it once that update is approved or, for a verified agent, applied.

What happens on disconnect and uninstall

Disconnecting your agent from a container keeps its skill and instructions there, because the agent still manages the container. Uninstalling removes both. The full list of what each one keeps is on Connecting agents.