Administer

Governance

How standards reach the work#

Citizen developers build with coding agents such as Claude Code, Codex, claude.ai and ChatGPT. Governance is how your engineering practices reach those agents. You write the practices down as skills, Markdown files of instructions, and agents read them while they work.

Two paths carry them:

• 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 plugin for Claude Code and Codex. Its publishing skill gives the same instruction, and the plugin installs the MCP server with it.

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.

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 dashboard's Governance page lists governance and every skill it names, each marked Default for Valet's version or Custom for your organization's. 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 instead from its next read on. 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.
• Dashboard. Open Governance, choose the skill, and select Edit. The first save creates your organization's copy.
• CLI. valet skills show security --org acme > SKILL.md saves the current text to start from. The CLI reads skills but doesn't publish them.

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

To restore Valet's version, delete yours. On the skill's page, open the ⋯ menu and choose Remove integration. Valet refuses the delete while a hosted agent has the skill attached.

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 Governance page 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 under Integrations, Add integration, Write a custom skill, or with publish_skill. The dashboard editor edits SKILL.md only, so publish a skill with supporting files through publish_skill.

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

org:<name> attaches your organization's skill and follows its new versions; org:<name>@v2 pins one. catalog:<name> attaches a skill from Valet's curated catalog, which valet skills catalog lists; no MCP tool does. To attach a built-in, save your organization's copy first. See Skill library for versions, attachment, and the rest of the 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 the coding agent, and Valet doesn't enforce them. It doesn't check a publish against them, and a publish that ignores them goes through.

Valet enforces these whatever the skills say:

• New artifacts and apps start private. Only organization members can open them until someone changes the access. The exception is an anonymous artifact, published without an account, which is always public.
• Valet checks access on every request. It checks the access mode before an artifact or app sees the request, and checks membership again each time.
• Connector credentials stay with Valet. Valet adds the credential to each call on the way out. Agents and pages in the browser never receive it. An app does read the env vars set on it, secrets included. See Connectors.
• A public artifact can't call connectors. Valet refuses the call.
• Connector packages are at least 7 days old. npm and Python packages an agent's connectors install resolve only releases published 7 or more days ago.
• A publish over MCP names the thing. publish_site and publish_app refuse a call with no title or description, and an app needs a Procfile at its root.
• Caps. Valet limits how many agents, artifacts, apps and resources an organization can create, how large one publish can be, and how often an artifact can call connectors. Members can't change caps.
• Isolation. Each app and agent runs in its own isolated runtime. An artifact runs no code on Valet's servers. See Security model.

Valet doesn't check the rest, so only skills cover it:

• Secrets in published files. The security skill tells the agent to search for them.
• An app's packages: their age, exact versions and licenses. An app's build installs what its manifest declares.
• Code-level rules, such as input handling, permission checks on the server, and debug servers in a Procfile.

Who can change governance#

Organizations have no roles, so any member can publish, replace or delete any skill, governance and security included. The change reaches every agent at its next read, with no approval step and no notice to other members.

Valet keeps each version of an organization skill with the time it was saved, but not who saved it. valet skills info <name> lists the versions. get_skill always returns the latest. See Organizations.