Skill

A markdown file of house rules, attached to the roles that need it, so you write your conventions once.

In simple words

A skill is a markdown file you write once and attach to an agent. Use it for the things that should always be true about your codebase: your conventions, your security rules, the “we do not do X here”.

It is the note you would hand a careful new colleague on their first day.

# API conventions

- Every endpoint validates its input at the boundary. Reject unknown keys;
  never coerce them.
- Errors return a typed code. Callers branch on the code, never on the message.
- No `console.log` in source. Use the logger in `src/logger.js`.

That is a whole skill. It lives under .vibestrate/skills/, and you attach it on the Crew page: vibe ui opens the dashboard on 127.0.0.1:4317, and every role card there has a Skills field.

Tip

A skill is the cheapest fix for “the model keeps doing the thing I told it not to”. Try it before a custom flow or a policy: far less machinery, and it applies to every task.

What belongs in one

Conventions Naming, error handling, which logger, which test style.

Things that bit you before “This module is load-bearing, do not refactor it casually.”

Domain knowledge What a term means in your business, which a model cannot infer.

Boundaries Which layers may talk to which, and what never crosses.

Did you know

A skill written as a directory can carry MCP servers, which means attaching one hands a role new tools as well as new instructions. A flat .md skill never does. That is why skill assignment is gated the same way a prompt edit is: it is the same class of authority, not a lesser one.

Attach one to a role

Crew in the sidebar opens the roster, and clicking a crew opens its detail page. Each role card there carries a Skills field with a + skill… picker listing everything discovered in this project, and each attached skill sits as a chip with an x to detach it. A card writes each change as you make it. The + beside Crew starts a new crew in the crew editor, which Edit roles on the detail page also opens; that editor is the one that holds every role behind a single save.

vibe shell puts the same thing on its Skills page (8) as a grid: ↑↓ picks the skill, ←→ picks the agent, ↵ or space toggles the pair.

The commands are the automation path:

vibe skills list
vibe skills show <name>
vibe skills assign <agent> <skill>
vibe skills unassign <agent> <skill>

assign and unassign write one field, a role’s skills list under crews.<crewId>.roles in project.yml; list and show only read. There is no top-level agents: key:

crews:
  default:
    roles:
      planner:
        skills: [payments, error-handling]

Attach one to a step, or to a single run

Knowledge belonging to a phase rather than a worker goes on the step. The Flow Builder’s step inspector has a Skills (this step) picker, added to that step’s prompt on top of the run’s own skills and carried by the flow when you share it.

For one task and no longer, the CLI takes them inline. This flag has no dashboard equivalent today:

vibe run "Refund a stuck transaction" --skills payments,oncall-runbook

Where they come from, and what is gated

More > Project lists every skill discovered under .vibestrate/skills/ and .claude/skills/, with its source beside each name. When that list is empty the page offers a Fetch skill box for an http(s) URL, as does the step inspector; vibe skills fetch <url> is the same install.

Installing is guarded rather than gated: private hosts refused, the body capped at 256 KB, secret-shaped content redacted, no overwrite unless you ask. Nothing reads a fetched skill until it is assigned.

Assignment is the gated half. From the dashboard it crosses the Action Broker as a file.write naming both project.yml and the role’s own instruction file, so a policy denying file writes refuses it in that policy’s own words. Allowed or refused, the decision is recorded in .vibestrate/runs/roles/actions.ndjson, the audit bucket for authoring that happens outside any run. vibe skills assign and the shell write the same field without that gate, and leave no such record. See safety.

Skills and project rules

.vibestrate/rules.md loads for every agent on every run. A skill loads only for the agents and runs that ask for it - a smaller circle inside the same one:

Common mistakes

Everything in one skill. A 5000-word file is hard for any agent to weigh. Split by surface - auth, payments, errors - and attach only what each agent needs.
Writing skills like prompts. Do not say “you are an expert at…”. State the convention. Agents read skills like docs.
Ephemeral info. “Fix the bug in PR #123” belongs in the task description.

Extending: add a skill - the file layout, the frontmatter, and the directory form that carries an MCP server.
Attach skills (getting started) - the quick path to your first one.