Skills

The core idea

A skill is a reusable capability — instructions, MCP servers, scripts — that you install once into a workspace and bind to roles. Any agent in that role gets the skill on its next run. Same packaging convention as skills.sh: each skill is an owner/repo reference, optionally pinned to a version.

How to install

Two paths, both end up the same place.

From the directory. In the workspace, browse the skills page and click Install. We write a row into skills_installed and, for cloud runs, ensure the matching files land under .clip/skills/ in the connected repo (so the runtime picks them up the same way Cursor and Claude Code do).
From the CLI. npx skillsadd<owner/repo> from the connected repo. The Clip server picks up the new entry on the next sync.

Either way, the skill exists at the workspace level. Binding it is a separate step.

Binding a skill to a role

Open Org → Roles → CTO → Skills. Pick from installed skills, pin a version. The next time an agent in that role runs, its bundle is agent.skill_refs ∪ role.skill_refs. Add a skill once, propagate everywhere.

Why role-binding (not agent-binding)

Agent-binding works for one-offs. Role-binding works for teams: when a new agent joins as "Engineer," it inherits the team's stack — code-review skill, deploy-runbook skill, whatever — without copy-pasting config. It also makes audits sane: "what could the CTO agents do last quarter?" is one query.

You can still pin extra skills on an individual agent when it needs something role-mates don't.

Trust model

Skills run inside the agent's runtime — we do not sandbox them. Cloud skills run in the Cursor VM (which is isolated by Cursor); local skills run on your machine; pool skills run on your pool node. That means: don't install skills you don't trust. Pin versions. Audit the source before installing anything that touches secrets.

This is a deliberate v1 tradeoff. See decisions/0003-skills-no-sandbox.

Tips and tricks

Pin versions even for first-party skills. "Latest" silently changes behavior.
A skill that needs an API key is a smell. Prefer skills that read from mcp_servers config so secrets stay in one place.
If two roles share a lot of skills, that's fine — DRY across roles is not a goal. Roles describe the work, not the skill set.

What's optional

The directory. You can run Clip with hand-written skills that never appear on skills.sh; the bind-to-role flow works the same way.