Add a skill

A skill is a markdown file teaching your agents your project’s conventions. There is no scaffold to run and no metadata form: write the file, and discovery picks it up.

mkdir -p .vibestrate/skills
$EDITOR .vibestrate/skills/api-conventions.md

Attaching it is the dashboard’s job. vibe ui (127.0.0.1:4317) > Crew > open a crew > each role card has a Skills block with a + skill… picker. Whatever you attach is appended to that role’s prompt on every turn.

A file in .vibestrate/skills/ named for the skill, like auth-conventions.md. The filename minus the .md is the name you refer to it by everywhere else, so keep it short and kebab-case; a name: in the frontmatter overrides it.

Plain markdown, no required structure. Most useful skills look like this:

# Title - what this is about

## When to use this

One or two sentences naming the surface.

## Rules

- Bullet list of conventions.
- Be specific. "We use X" beats "we prefer X".

## Examples

Short examples of the right way.
Mark anti-patterns explicitly.

More > Project has a Skills section listing everything Vibestrate found, with the file path behind each name. When the list is empty it offers a Fetch skill box that pulls one from an http(s) URL.

The same read, in a terminal:

vibe skills list
vibe skills show <name>

A skill does nothing until it is attached to something.

To a role, permanently. Crew editor, role card, Skills, + skill…, then Save in the masthead. vibe shell does the same on its Skills page: ↑↓ picks the skill, ←→ picks the agent, ↵ toggles the pair. The CLI writes to project.yml:

vibe skills assign <agent> <skill>
vibe skills unassign <agent> <skill>

Either way the result is the role’s skills list, under crews.<crewId>.roles - there is no top-level agents: key:

crews:
  default:
    roles:
      planner:
        skills: [auth-conventions]
        # plus seats, profile, prompt and
        # permissions, which stay required

To one step of a flow. The Flow Builder’s step inspector has a Skills (this step) picker, for knowledge that belongs to a phase rather than to a worker.

To one run. When the skill matters for this task only:

vibe run "Add 2FA" --skills auth-conventions

Write it like docs for a colleague, not a prompt: what you would tell a new engineer on day one, minus the persuasion.

• Name the surface. “When touching src/payments/...” beats “for payment changes.”
• State the rule, not the reasoning. “Use requireSession from src/server/auth.ts” beats “we care a lot about security.”
• Mention the anti-pattern. “Don’t write session middleware inline.”
• Keep it bounded. A 200-line skill loading on every agent is expensive; split one that grows.

A skill can declare an MCP server (an outside tool an agent connects to). A flat .md file has nowhere to keep the config, so use the directory form: a folder named for the skill id, holding SKILL.md (or skill.md) plus a sibling .mcp.json.

.vibestrate/skills/
  postgres/
    SKILL.md
    .mcp.json

SKILL.md is the same plain markdown as a flat skill, with optional name / description frontmatter:

---
name: postgres
description: Read-only Postgres access.
---

# Postgres MCP

This skill grants agents read-only Postgres
access, for inspecting queries.

.mcp.json declares the server: the command to run, plus optional args and env. Only the stdio transport is supported, and the command is a plain argv[0], never passed through a shell:

{
  "mcpServers": {
    "postgres": {
      "command": "pg-mcp",
      "args": ["--read-only"]
    }
  }
}

Most skills need none of this. A flat .md skill’s mcpServers is always empty.

• Skill (concept) - what a skill is and how agents use it.
• Attach skills (getting started) - the quick path to your first one.