Skip to main content

​
What a skill actually is

A skill is a short instructional document, usually a markdown file with a YAML header, that an agent reads alongside its tool catalog. The MCP server tells the agent what tools exist; the skill tells it when and how to use them. For Lavendly, the skill captures four things:
  1. The canonical call sequence. Probe capabilities → check budget → create the workflow → wire audio → render → poll. Skip steps and you waste money or produce bad output.
  2. The decision rules. When to use mix vs native audio, when to add captions, when to render single-shot vs multi-clip.
  3. The idempotency discipline. Which calls cost money, which need keys, how to construct keys that survive retries.
  4. The taste. What “a good Lavendly video” looks like, pacing, voice tone, music mood, when subtitles help vs hurt.
You can use the MCP server without a skill. But loading a skill turns an agent that can call Lavendly tools into an agent that produces good Lavendly output, cheaply, on retry.

​
How skills compose with the MCP

┌──────────────────────┐                ┌──────────────────────┐
│  Skill (markdown)    │                │  MCP server          │
│  - operating manual  │                │  - tool catalog      │
│  - decision rules    │  ─── agent ─▶  │  - input schemas     │
│  - example sequences │                │  - live calls        │
└──────────────────────┘                └──────────────────────┘
                                                   │
                                                   ▼
                                          Lavendly API
The skill is prompt-side. It lives in your agent runtime’s prompt or skill loader (e.g. ~/.claude/skills/, Cursor’s project rules, your own SDK harness). The MCP is action-side, it actually moves bits.

​
Ready-made skills

Storyteller

Narrated shorts from a one-line idea. Voice + music + captions.

Multi-clip

Consistent characters and palette across a sequence.

Cost-aware

Budget guardrails for autonomous loops.

Author your own

Write a custom skill for your use case.

​
Installing a skill

Skills are platform-specific. The same skill text gets loaded in slightly different ways: 
# Install all first-party Lavendly skills
npx -y @lavendly/skills install

# Or one at a time
npx -y @lavendly/skills install storyteller
The skill files land in ~/.claude/skills/lavendly/. Claude Code auto-loads them in any project that has the Lavendly MCP server registered.

​
Skill precedence, when skills disagree

You can load more than one skill at a time. When their rules conflict, Lavendly uses a deterministic resolution order:
1

`priority: high` wins over `priority: normal`

Skills declare priority in their YAML frontmatter. cost-aware ships as priority: high because its budget rules must override domain choices that would otherwise overspend. Domain skills (storyteller, multi-clip) default to priority: normal.
2

Within the same priority, later wins over earlier

Skills are read in the order they’re loaded. If two priority: normal skills both pick a music mood, the later skill’s rule wins. Order your loader explicitly.
3

Tool catalog is never overridden

Skills cannot remove tools from the MCP catalog or add new ones. They can only constrain which tools to call and how.
In practice: load cost-aware first (its budget rules apply everywhere), then the domain skill that fits the current task. The resulting prompt looks like: 
const system = [
  baseSystem,
  loadSkill('cost-aware'),    // priority: high, applies globally
  loadSkill('storyteller'),   // priority: normal, domain choices
].join('\n\n');
Or in Python: 
from lavendly.skills import load_many
system = base_system + "\n\n" + load_many(["cost-aware", "storyteller"])

​
Conflict resolution at a glance

DisagreementWinner
cost-aware: refuse render if available < 20. storyteller: render anyway.cost-aware (high priority)
multi-clip: cap at 30 s. User brief asks for 60 s.multi-clip (skill rule beats user nicety)
Two normal-priority skills pick different music moodsLast loaded wins
Skill says “use tool X.” MCP catalog doesn’t include X.Tool catalog (skill cannot invent tools)

​
What’s not in a skill

A skill is not:
  • A second tool catalog. The MCP is the only source of truth for what tools exist and what they accept.
  • A cache of API responses. Tool calls always hit the live API.
  • A place for your API key. Keys come from the MCP server’s env.
Skills are pure prompt material. Editing one never changes what the platform can do, only how the agent reasons about it.