Administer

Governance

How standards reach the work#

Your engineering practices reach coding agents through skills, Markdown files of instructions that agents read while they work. Citizen developers using Claude Code, Codex, claude.ai or ChatGPT receive them in two ways:

• Valet's MCP server. Its instructions tell every connected agent to call get_skill with governance before any work, and again before any publish. This reaches agents with no terminal, such as claude.ai and ChatGPT.
• The valet skill, in the Valet plugin for Claude Code and Codex or installed on its own. It gives the same instruction. An agent that works through the CLI reads governance with valet skills show governance --org <org>. The plugin installs the MCP server with the skill.

The governance skill names the other skills to read and when. It then tells the agent to call list_skills and read every other skill whose description fits the task, which is how agents find your own skills. From the CLI, valet skills --org <org> lists them.

The built-in skills#

Every organization starts with Valet's skills. Skill names follow the MCP tools, so sites covers artifacts.

governance leads to platform, security, dependencies and design-system, and platform leads to the rest.

The Standards tab of the dashboard's Governance page lists governance and every skill it names, each marked Default for Valet's version, Custom for your organization's, From the catalog for one installed from the catalog, or Not written for a named skill that doesn't exist. Its Policies tab holds your release policies. get_skill reads any of them, as does valet skills show <name>.

Floors and defaults#

The skills mark each rule a floor or a default:

• A floor holds even when the person asks to skip it. The agent says why and offers a safe way to get what they want.
• A default holds unless the work has a reason to differ. The agent says what it did instead.

A floor, from security:

### 2. Let Valet decide who gets in

Build no sign-in page, password check, or user table to keep people
out. The access setting is the gate, and one Valet sign-in covers every
site and app in the organization.

A default, from dependencies:

### 8. Name exact versions

Write `"1.4.2"`, not `"^1.4.2"` or `"latest"`, and `requests==2.32.3`,
not `requests>=2`.

Replace a built-in skill#

Publish a skill with the same name as a built-in, and every agent in your organization reads yours the next time it requests the skill. Your file replaces all of Valet's text; nothing is merged.

• MCP. Ask a connected agent to publish it. It calls publish_skill with the SKILL.md and any supporting files; the first publish creates your organization's copy. To change part of a copy you already have, it sends edits with the base_version that get_skill reported.
• Dashboard. Open Governance, choose the skill on the Standards tab, and select Edit. The first save creates your organization's copy.
• CLI. valet skills show security --org acme > security/SKILL.md saves the current text to start from. Edit it, then run valet skills create ./security --org acme for your first copy, or valet skills publish ./security --org acme after that.

get_skill tells the agent which version it holds: source: org for yours, source: default for Valet's.

To restore Valet's version, destroy yours: an agent calls destroy_service, or you run valet skills destroy <name> --org <org>, or on the skill's page you open the ⋯ menu and choose Remove integration. Valet refuses while a hosted agent has the skill attached, and the copy can't be renamed while it replaces a built-in.

If you replace governance, keep two things from Valet's version:

• The instruction to call list_skills. Without it, agents stop finding your other skills.
• The metadata.governs frontmatter. It lists the skills the Standards tab shows. Add your own skills' names to show them there. A name you list but haven't written shows as Not written, with a button to write it.

Write your own standards#

Add a skill under a new name for each standard of your own. Agents choose what to read from each skill's description, so make the description say when to read the skill, as the built-ins do.

---
name: data-storage
description: Read before giving an app a database or writing code that stores records. It says which database our apps use and how we name tables.
---

# Data storage

## Floors

### 1. Use the shared operations database

Attach the `ops-db` resource to any app that keeps records. Never
create another database resource. If `ops-db` does not fit, stop and
tell the person to ask the platform team in #platform-help.

## Defaults

### 2. Name tables in the plural, in snake_case

`purchase_orders`, not `PurchaseOrder`.

A standard is an ordinary skill. Write one covers the format, and Publish it covers the limits. Two points apply to standards in particular:

• To replace a built-in, use its name.
• Your skills can use floor and default, which the governance skill defines for every agent.

Add one in the dashboard on the Skills page with Add skill, Write a custom skill. With MCP, call create_service with the kind skill, then publish_skill; with the CLI, run valet skills create. The dashboard editor changes only the files a skill has. Add, rename or remove files through MCP, the CLI or Git.

Give a skill to a hosted agent#

A hosted agent loads the skills attached to it. Attach one to give it your standard:

attach_skill
{ "name": "support-bot", "skill": "org:data-storage" }

You can attach a built-in skill before your organization has a copy. The agent holds Valet's default, and moves to your copy once you publish it. For catalog skills, release updates and attachment rules, see Skill library.

The design system#

The design-system skill is your organization's house style: palette, type, layout and voice. The governance skill tells agents to read it before building anything people look at, so every page they publish comes out looking like you.

Set it in the dashboard under Team, Settings, Design system. Choose one of four built-in styles, Atlas (the default), Folio, Dispatch or Studio. Or have Valet draft one from your company's website, or write your own. Your own is an ordinary design-system skill, replaced like any other built-in.

The agent applies the style when it creates or rewrites a page. A person's instruction for one page wins, and a finished file handed over for publishing is published unchanged. Valet doesn't restyle pages.

What governance guides, and what Valet enforces#

Skills guide coding agents. Valet doesn't check whether a publish follows them, so a publish that ignores them goes through.

To enforce checks before a release goes live, add release policies. Valet supplies checkers for credentials in source files and known package vulnerabilities. A blocking policy refuses a failed release and keeps the current release live. Package age, licenses and code-level rules need a custom checker if you want Valet to enforce them.

Valet enforces access controls, credential handling, isolation and connector package restrictions independently of skills. See Security model for those protections and their limits. Publishing also requires:

• A title and description for publish_site and publish_app calls with files. A push reads them from the commit's valet.yaml, if present. See MCP server.
• A Procfile at the root of every app.
• Compliance with publish-size limits and organization caps. See the limits on artifacts and resources. Members can't change caps.

Next steps#

• Skill library: manage skill releases and attachments.
• Release policies: enforce checks at publish time.