Build

Skills

On this page

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.

On Valet a skill is a service, like a website, an app or an agent. It has a name that no other service in your organization shares, an author, a star, and a history of releases. list_services lists it, and rename_service and destroy_service rename and remove it. Unlike an app or an agent, a skill runs no process and has no web address.

Start with a skill

If you've explained a task to your coding agent more than once, write it as a skill. All you need is clear writing; no server, code or data access is required.

A skill can guide a coding agent building an app or become part of a hosted agent's instructions. If you need a page, server code or work that runs on its own, choose the tool type that fits.

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

Create the skill, then publish it. Ask your agent:

Publish the ticket-triage skill to Valet.

Your agent creates an empty skill. The name must be 3 to 63 characters and can't match another service in your organization. Next, it opens a push or sends the files.

create_service
{ "kind": "skill", "name": "ticket-triage" }

An agent that can run Git with network access publishes from a push. It sends only what changed, and a push carries any file, scripts and images included:

create_push
{ "name": "ticket-triage" }

The agent runs the returned commands, then publishes the commit:

publish_skill
{
  "skill": "ticket-triage",
  "push": { "id": "…", "commit": "…" }
}

Without Git, the agent sends text files in the call. The first release sends the whole skill with 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…" }
  ]
}

With the CLI, create the skill from a folder, then publish changes from the same folder:

No MCP tool does this. Use the CLI.

In a folder linked to the skill, valet deploy publishes it too.

files replaces the whole skill and removes any file the call leaves out, binary files included. To change some files of a skill that exists, the agent sends edits instead; see Update it.

valet skills publish removes files no longer in the folder and skips publishing if nothing changed. The MCP server and the CLI both publish. 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. On the Skills page, choose Add skill, then Write a custom skill. To add more files after that, use Git, the CLI or MCP.

A skill holds up to 500 files and 50 MB, with at most 25 MB per file. These are the same limits as for artifacts, apps and agents. Without Git, one publish_skill call with files or edits carries up to 50 text files, 128 KiB each, and 192 KiB in all.

How teammates use it

Valet's MCP server tells every coding agent connected to it to call list_skills when a task might be covered by how your organization works, and to read each skill whose description fits. This applies to all work for the organization, including work outside Valet. Your organization's governance skill says the same before Valet work. 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 text file with the same tool. The CLI prints SKILL.md, and a supporting text file with --path: valet skills show ticket-triage --path owners.md. Neither returns a binary file, such as an image; clone the skill to get those. For a coding agent that has no shell, get_skill with all_files returns every text file of the skill in one answer, so the agent can write the folder itself. Either way, the copy doesn't follow later releases.

Update it

To change a skill, publish it again under the same name, or open it from Skills in the dashboard and choose Edit. The dashboard editor changes any of the skill's text files; add, rename or remove files through Git, the CLI or MCP. Each change creates a new release, numbered v1, v2, and so on. Publishing identical content creates none and reports deduped. Coding agents get the latest release the next time they read the skill.

To change some files and keep the rest, the agent sends edits with the version get_skill reported as base_version:

publish_skill
{
  "skill": "ticket-triage",
  "base_version": 3,
  "edits": [
    { "path": "owners.md", "content": "| Feature | Team |\n| --- | --- |\n…" }
  ]
}

If a teammate published a newer release since the agent read it, Valet publishes nothing and refuses with deploy.source_moved. The agent reads the skill again and redoes its change. base_version works with files and push too. The dashboard editor sends it for you, and valet skills publish doesn't: it replaces whatever version is latest.

To start from the latest release, clone it. get_skill with git returns a read-only clone URL, and the CLI clones into a folder:

No MCP tool does this. Use the CLI.

Edit the files, then publish them as above. get_skill with git also reports the version to pass as base_version.

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

No MCP tool does this. Use the CLI.

The same list is in list_releases, and the skill page in the dashboard lists every release and opens any one. valet skills show with --release prints an earlier release. A coding agent reads an earlier release with get_skill and release. Restoring an earlier release works as it does for a website: read it, then publish its files again, which makes a new release.

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" }

Attaching rebuilds and redeploys the agent. It follows the skill's latest release; pins are ignored. For update timing, fixed instructions and attachment rules, see Skill library.

Start from a catalog skill

Valet's catalog holds skills you can copy. An install makes a skill your organization owns; it doesn't change when Valet updates the catalog.

Your agent installs one with create_service. To keep another name, it passes name too, and Valet sets the skill's name to it.

create_service
{ "kind": "skill", "name": "premortem", "catalog": "premortem" }

Attaching catalog:<name> to an agent installs the copy the first time and reuses it after, even if you renamed the copy. If another service in your organization already has that name, the install is refused with skill.name_taken. Install it under another name, or rename the other service.

Rename it

rename_service
{ "name": "ticket-triage", "new_name": "support-triage" }

The skill keeps its history and its attachments. Valet publishes a release whose SKILL.md carries the new name, and answers with the agents that have the skill attached, so you can update any instructions that name the old one. Those agents use the new name the next time they start. Renaming doesn't redeploy or wake them. Valet refuses the rename when an attached agent's own skills folder already holds a skill of the new name, and it refuses to rename a skill that replaces one of Valet's built-ins. A valet.yaml that still lists the old name doesn't block a deploy; it shows in the Blueprint as a suggestion.

Destroy it

destroy_service
{ "kind": "skill", "name": "ticket-triage" }

Valet refuses while an agent has the skill attached, with skill.in_use naming the agents; detach it from each first with detach_skill. Once it's gone, the name is free to use again. If the skill replaced a built-in, Valet's version answers again.

Who can use it

A published skill belongs to your organization. Every member's coding agent can read it, and no one outside the organization can. For ownership, release history and distribution, see Skill library.

Next steps

Skill library: manage ownership, releases and distribution.
Governance: turn a skill into an organization standard.