Skip to main content

​
When to write a skill

The first-party skills (storyteller, multi-clip, cost-aware) cover broad use cases. Write your own when:
  • Your brand has a specific voice (e.g. always punchy, never whimsical) that the generic skills miss.
  • Your team renders a specific format (vertical 9:16, square 1:1, exactly 6 seconds) and you don’t want to re-explain it every prompt.
  • You’re building an internal tool on top of Lavendly and want a consistent agent behavior across coworkers.

​
Skill anatomy

A Lavendly skill is a markdown file with a YAML frontmatter header and a body. The body is just instructions to the agent. 
---
name: my-team-skill
description: One sentence on what the skill produces.
trigger: When the agent should activate this skill.
priority: normal       # 'high' = override conflicting skills, 'normal' = layer
---

# {Team / brand name} · {Use case}

## Sequence
...

## Decision rules
...

## When to bail
...

​
The four sections that matter

The literal sequence of MCP tool calls the agent should make. Number them. Be specific. If a step has substeps (drafting a script before attaching a voiceover), list those too.This is the single highest-leverage part of the skill. Agents without explicit sequences improvise, and improvisation in a paid API is expensive.
Cover the choices the agent will hit. Examples:
  • “If get_status.voice.supports_inline_tags is true, use emotion tags.”
  • “If the brief mentions dialogue, use mix audio. Otherwise off.”
  • “If the user names a specific aspect ratio, honor it. Otherwise default to 9:16.”
Skip rules that are already obvious from the tool descriptions, only write rules that disambiguate.
Tell the agent when to STOP and ask for help instead of pushing through. Without this section, agents will loop on a doomed render until your budget is empty.Useful patterns:
  • “If the user’s request is over 30 s of total video, ask if they want to split into multiple workflows.”
  • “If get_render returns failed twice with the same error code, stop and report.”
  • “If get_monthly_usage.fraction_used > 0.85, refuse non-urgent work.”
Optional but high-impact. Constrain how the agent makes creative choices. Examples from real teams:
  • “Voiceovers always present tense, never past.”
  • “Music is always instrumental, no vocal beds, ever.”
  • “Avoid the phrases ‘in a world where,’ ‘once upon a time,’ or anything starting with ‘imagine.’”
This is what makes the agent feel like your agent, not a generic one with your API key.

​
Loading your skill

cp my-skill.md ~/.claude/skills/lavendly-my-skill.md
Restart Claude Code. The skill auto-loads when its trigger matches.

​
Testing your skill

Two cheap tests before you ship:
  1. Cold-start test. New agent session, fresh model context, no prior conversation. Give it the trigger prompt. Does it follow your sequence on the first try? If not, the sequence section needs tightening.
  2. Adversarial brief. Give it a request that violates your constraints (a 60 s video when the skill caps at 12 s, a vocal music track when you said instrumental). Does it bail correctly? If it pushes through, the When to bail section needs to be stricter.
Both tests cost one or two renders worth of credits, much cheaper than discovering the gap in production.

​
Sharing skills

Skills are markdown. Commit them to git, ship them in your team’s runbook, paste them into Slack. They have no secrets and they’re trivially reviewable. Treat them like documentation that the agent actually reads.