> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lavendly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Author your own skill

> Write a custom Lavendly skill for your team's voice and use case.

## 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.

```markdown theme={null}
---
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

<AccordionGroup>
  <Accordion title="Sequence, the canonical call order" icon="list-ol">
    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.
  </Accordion>

  <Accordion title="Decision rules, the if-then logic" icon="code-branch">
    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.
  </Accordion>

  <Accordion title="When to bail, the stop conditions" icon="hand">
    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."
  </Accordion>

  <Accordion title="Taste, the brand voice" icon="palette">
    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.
  </Accordion>
</AccordionGroup>

## Loading your skill

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    cp my-skill.md ~/.claude/skills/lavendly-my-skill.md
    ```

    Restart Claude Code. The skill auto-loads when its trigger
    matches.
  </Tab>

  <Tab title="Cursor">
    ```bash theme={null}
    mkdir -p .cursor/rules
    cp my-skill.md .cursor/rules/lavendly-my-skill.md
    ```

    Cursor reads project rules on every Composer thread.
  </Tab>

  <Tab title="Custom runtime">
    Concatenate the skill body into your system prompt:

    ```js theme={null}
    const skill = await fs.readFile('skills/my-skill.md', 'utf8');
    const systemPrompt = `${baseSystem}\n\n${skill}`;
    ```

    Pass the rest as MCP tools.
  </Tab>
</Tabs>

## 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.