Extensibility

Skills

Bundle instructions, assets, and scripts the Assistant pulls in on demand. A skill teaches the Assistant a repeatable workflow it loads only when the situation calls for it.

Plugins are in beta. The plugin API (@vellumai/plugin-api) is not yet stable and can change between releases. Pin the peerDependencies range your plugin declares, and expect breaking changes until we cut a 1.0. Skill layout and frontmatter fields can change with it.

A skill is a directory with a SKILL.md at its root. The file is YAML frontmatter followed by a markdown body: the frontmatter tells the Assistant what the skill is for, and the body is the instructions it follows once the skill is active. A plugin ships skills under skills/<name>/, and the skill catalog loader discovers them on disk.

What a skill is

A skill is a bundle of instructions and supporting files that the Assistant loads into context when the conversation matches what the skill is for. Nothing runs on its own: the skill gives the Assistant a procedure to follow, plus any scripts or assets it ships alongside.

The Assistant decides when to load a skill from its description and activation hints, so write those fields for the model: say what the skill is for and the situations it should fire in.

Frontmatter reference

These are the fields the SKILL.md frontmatter can set. Only name and description are required; everything under metadata is optional and refines how the skill is presented and matched.

FieldTypeRequiredDescription
namestringYesSkill identifier. Keep it stable, since the Assistant refers to the skill by this name when it loads it.
descriptionstringYesWhat the skill does and when to use it. The Assistant matches against this to decide whether to load the skill, so write it for the model, not for a human reader.
metadata.emojistringNoGlyph shown next to the skill in clients that render a skill list.
metadata.vellum.display-namestringNoHuman-friendly label for the skill. Falls back to name when omitted.
metadata.vellum.activation-hintsstring[]NoPlain-language situations where the skill should activate. These sharpen the match beyond the description.
metadata.vellum.avoid-whenstring[]NoSituations where the skill should not activate, used to keep it from firing on adjacent-but-wrong requests.
metadata.vellum.categorystringNoGrouping used when the skill is listed in a client. Defaults to "system".

Anatomy of a skill

One skill per directory. The SKILL.md is required; assets and helper scripts are optional and live alongside it:

plugins/my-plugin/
└── skills/
    └── standup-notes/
        ├── SKILL.md        # Frontmatter + instructions (required)
        ├── references/     # Optional docs the instructions cite
        └── scripts/        # Optional helper scripts the skill runs
            └── post_summary.ts

The SKILL.md itself is frontmatter plus the procedure the Assistant follows once the skill is active:

---
name: standup-notes
description: >-
  Draft a daily standup update from recent activity. Use when the user
  asks for their standup, daily update, or what they did yesterday.
metadata:
  vellum:
    display-name: "Standup Notes"
    activation-hints:
      - "User asks for their standup or daily update"
    avoid-when:
      - "User wants a full weekly report, not a daily standup"
---

Draft a concise standup update with three sections: Yesterday, Today,
and Blockers.

## Steps

1. Summarize what was completed since the last standup.
2. List what the user plans to work on today.
3. Call out any blockers, or write "None" when there are none.

Keep each section to a few short bullet points.

See the Extensibility overview for how skills sit alongside the other surfaces a plugin can bundle.

The Personal AI you were promised

GET STARTED