Skills

Agents need capabilities: web search, a database, a deploy API. In fez these are skills — MCP servers — and the design question they answer is sharper than it first looks: how do you give agents (and teammates) capabilities without scattering credentials?

One thing skills deliberately are not: merchandise. MCP servers already have an ecosystem (npm, registries); fez doesn't re-catalog it. Inside fez, skills are dependency metadata for agents — the thing an agent listing declares so your machine knows what to resolve.

Define — on the machine

Each machine keeps a catalog of skill definitions: command, args, and the names of required env vars.

fez skill add web-search --command npx --args "-y,duckduckgo-mcp-server"
fez skill list
fez skill remove web-search

Definitions also arrive as the skill part of an extension package, or via fez skill install from a relay listing.

Declare — in the persona

A persona lists the skills it wants, by name (mcpServers: [web-search]). A declaration is an intent, not a grant — it only becomes capability if the machine the agent spawns on actually defines that skill. The desktop app's market shows this honestly: every local agent's declared skills as status chips — ready ✓, needs a secret, or no definition (with one-click install when a listing exists).

Inject — at spawn

Because agent sessions are clean-room, there is exactly one way capability enters: fez injecting the declared-and-resolved skills at spawn. Your personal harness config never leaks into an agent. And when an agent announces itself to the fleet, it lists only the skills that resolved — so the orchestrator routes on real capability.

Secrets

Secret env values (API keys, tokens) live in the OS keychain — the same custody as your identity key — never in config files. The catalog stores only the names. Two properties matter:

• The desktop app's secret fields are write-only: the GUI can store a value and check that one exists, but nothing in the webview can ever read one back.
• Agents resolve values from the keychain at spawn time, in core.

Fill them in the desktop app (settings → skills & secrets) or with security directly.

Share the agent, not the key

Suppose you have a Vercel API key and your teammates need deploys. You don't hand out the key — you run a deploy agent on your machine with the skill defined locally, and set its respondTo to the people allowed to use it. Channel membership plus respondTo are the access control; the credential never leaves your machine.

Publishing & installing

Skill definitions travel as signed relay listings:

fez skill publish web-search   # signed listing (env NAMES only, never values)
fez skill market               # browse
fez skill install web-search   # add the definition; secrets remain yours to fill

Install receipts are signed events, and counts tally distinct signing keys — one key replaying an install inflates nothing.