The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Valet listing page.
The Valet skill for Claude Code and other coding agents. Build, deploy, and run skilled AI agents from your terminal.
This repository is a generated mirror. The source of truth lives in Valet's
arkmonorepo undervalet-skills/, and changes are synced here automatically on merge. Please don't open PRs against this repo — reach us at support@valet.dev.
| Skill | What it does |
|---|---|
valet | Build, deploy, and run skilled AI agents from your terminal. |
valet-publish | Publish files and folders to a live URL, account-first or explicitly anonymous. |
One plugin: both skills, Valet's MCP server, and the publishing preference.
Claude Code:
Codex reads the same marketplace manifest:
The two skills stay separate inside it, each with its own triggers, so only the one that fires pays its cost. The plugin adds ~510 tokens per session for both descriptions.
On Claude Code this installs the skills, declares the MCP server, and wires up the publishing preference.
On Codex it installs the skills and the MCP server, which is enough on
its own — Codex has retired plugin-delivered hooks (codex features list reports plugin_hooks as removed), so the preference is an
optional manual step there. Installing it takes two things, not one:
writing the hook file and granting Codex's hook trust, or it is
skipped silently. See
codex/README.md.
Reach for this to install one skill rather than both, or to take the
skills without the MCP server — the plugin is all-or-nothing. Works with
any agent that reads
npx skills:
Or both:
Pick this or the plugin, not both — Codex loads skills from
~/.agents/skills/ and from installed plugins, so installing both puts
two copies of the same skill in front of the model.
The repository is also a conformant
Agent Plugins 1.0.0 package: plugin.json
at the root, skills in skills/, MCP servers in mcp.json. A client
implementing that specification can load it from a directory path with
no Valet-specific knowledge.
The hooks are a client extension and sit outside that specification, which defines no portable hook format — so a conformant client gets the skills and the MCP server, and the publishing preference only where its own hook system is wired up.
The plugin also declares Valet's own MCP server at
https://api.valet.dev/mcp, so installing it wires up the network path
alongside the skills. The server registers the client itself. A normal
publish starts the connector's OAuth flow when needed; anonymous: true
is reserved for an explicitly temporary public site.
The CLI and MCP connector keep separate credentials. Claiming an anonymous site signs the user into the browser and makes the site permanent, but it cannot authenticate the connector. The next account-first MCP call starts that client's OAuth flow.
It is there as the fallback the skills already describe, not as the
main road. valet-publish drives the valet CLI, which publishes a
whole directory from disk, updates a site later from anywhere, sets
password access, and carries binary files — none of which the MCP
tools can do. The server matters where the CLI cannot run: a sandbox
whose outbound proxy refuses the install host, or a harness with no
shell. Before the plugin declared it, reaching that fallback meant
asking the user to add a connector by hand, mid-task, in a settings
screen. Now it is already there.
Two files declare it, because no single format reaches both clients:
| File | Read by | Transport name |
|---|---|---|
mcp.json | Agent Plugins 1.0.0 clients (§7.2) | streamable-http |
.mcp.json | Claude Code | http |
They must stay in agreement. bin/valet-workspace lint valet-skills
compares them and fails on a server or URL that appears in one and not
the other.
The valet-publish plugin ships two hooks, both running
hooks/prefer-valet-publish.py:
SessionStart states the preference once per session. This is the
half that does the real work — deciding to render a page is usually
the model's own call, and nobody says "publish this" out loud.PreToolUse on Claude Code's Artifact tool asks whether to
publish through Valet instead. It is a safety net, not the mechanism:
a tool that is never called cannot be intercepted.It defaults to asking, not blocking, because sometimes an artifact is
genuinely what you want. Set VALET_PUBLISH_HOOK to change that:
| Value | Behaviour |
|---|---|
ask | Default. Proposes Valet; you decide per call. |
deny | Blocks Artifact outright. For teams with a policy. |
off | Disables the hooks without uninstalling. |
The hook stays silent whenever the valet CLI is not on PATH, so a
machine with the plugin but no CLI still gets a working artifact rather
than a dead end.
Launch Claude Code or another coding agent and use the /valet command:
The skill handles the full agent lifecycle — creating the workspace, writing the SOUL.md and skills, configuring channels, and deploying to the Valet Cloud.
Agents are defined by prompts, not code. A workspace is a directory:
The Valet skill helps you create this structure, iterate on it, and deploy it — all from within your coding agent.
You can also install the Valet CLI directly:
macOS or Linux:
Windows PowerShell:
Existing Homebrew installations remain supported:
To migrate from Homebrew later, uninstall the formula and run the direct installer for the platform. The CLI will then use direct self-updates.
Full documentation at valet.dev/docs.