Build

Skills

What a skill is#

A skill is written instructions for a coding agent: how your team reviews a vendor contract, how to pull last quarter's numbers from the warehouse, or what goes in the weekly report. It's a folder that holds a SKILL.md file, plus any supporting files the instructions refer to, such as a template or an example.

SKILL.md starts with a name and a description. An agent reads the description to decide when the skill applies, and reads the rest only when it does.

Claude Code, Codex, Cursor and other coding agents already use skills from a folder on your computer. That folder is yours alone, so a skill that works well helps only you. Publishing it to Valet puts it in your organization's library, where every teammate's coding agent can find it.

Start with a skill#

A skill is the simplest tool you can build. It needs no server, no code and no access to data, only clear writing. If you've explained a task to your coding agent more than once, you have a skill.

From there, the same work can grow into more:

• An artifact when people need a page to open, such as a report or a checklist.
• An artifact with a connector when the page should show live data from a service your company uses.
• An app when it has to save what people enter, or call an LLM with a key no browser should see.
• An agent when the work should happen on its own: on a schedule, in Slack, or when another system calls it.

The skill stays useful as the tool grows. The coding agent that builds your app follows it, and an agent you publish can carry it.

Write one#

Ask your coding agent to write it with you:

Write a skill for how our team triages support tickets, using what we
did today as the example. Call it ticket-triage.

A skill looks like this:

---
name: ticket-triage
description: Read when sorting or answering a support ticket. It says how we set priority, which team owns each kind of ticket, and what the first reply must include.
---

# Ticket triage

## Set priority

- P1: the customer can't use the product. Page the on-call engineer.
- P2: a feature is broken and there's no workaround.
- P3: everything else.

## Route it

Billing questions go to finance-ops. Bugs go to the team that owns the
feature; `owners.md` lists them.

• name: lowercase letters, digits and single hyphens, up to 64 characters.
• description: required, up to 1,024 characters. Say when to use the skill, not only what it covers, since agents choose from this sentence.
• The body is Markdown. Write it the way you'd brief a new colleague.
• Supporting files, such as owners.md above, sit beside SKILL.md. Say in SKILL.md when to read each one.

Publish it#

Ask your agent:

Publish the ticket-triage skill to Valet.

Your agent publishes SKILL.md and its supporting files:

publish_skill
{
  "files": [
    { "path": "SKILL.md", "content": "---\nname: ticket-triage\ndescription: Read when sorting or answering a support ticket. …\n---\n\n# Ticket triage\n…" },
    { "path": "owners.md", "content": "| Feature | Team |\n| --- | --- |\n…" }
  ]
}

Publishing a skill needs Valet's MCP server; the CLI reads skills but doesn't publish them. The Claude Code and Codex plugins include the server, and any other MCP client can add it with the server's URL; see Add it to your client.

You can also write a skill in the dashboard. Under Integrations, choose Add integration, then Write a custom skill. The dashboard edits SKILL.md only.

One publish over MCP carries up to 50 files, SKILL.md included. Each file can be up to 128 KiB, and the files together up to 192 KiB.

How teammates use it#

Every coding agent connected to Valet's MCP server reads your organization's governance skill before it starts work. That skill tells the agent to call list_skills and read every skill whose description fits the task. Once you publish ticket-triage, a teammate who asks their agent to answer a support ticket gets your instructions, even if they don't know the skill exists.

A teammate can also ask for it by name:

Use our ticket-triage skill on this ticket.

The agent reads it with get_skill, and reads a supporting file only when SKILL.md points to it.

To keep a copy in the folder your coding agent loads skills from, ask your agent:

Save our ticket-triage skill to my skills folder.

get_skill
{ "skill": "ticket-triage" }

get_skill lists the supporting files, and your agent reads each one with the same tool. The CLI prints SKILL.md alone. Either way, the copy doesn't follow later versions.

Update it#

To change a skill, publish it again under the same name, or open it from Integrations in the dashboard and choose Edit. Each change creates a new version: v1, v2, and so on. Publishing identical content creates none. Coding agents get the latest version the next time they read the skill.

To see the versions and the hosted agents that use the skill:

Give it to an agent#

An agent you publish can carry your skill, so it follows the same instructions when it works on its own. Ask your coding agent:

Attach our ticket-triage skill to support-bot.

attach_skill
{ "name": "support-bot", "skill": "org:ticket-triage" }

Valet rebuilds the agent so the change takes effect. The agent moves to each new version of the skill; attach org:ticket-triage@v2 instead to pin one. See Skill library for how new versions reach agents.

Who can use and change it#

A published skill belongs to your organization. Every member's coding agent can read it, and no one outside the organization can. Any member can publish a new version or delete it. Valet records when each version was saved, but not who saved it.