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

# Agent skills overview

> An MCP gives the agent tools. A skill teaches the agent how to use them well.

## 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](/mcp/overview) 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

<CardGroup cols={2}>
  <Card title="Storyteller" icon="book-open" href="/agent-skills/storyteller">
    Narrated shorts from a one-line idea. Voice + music + captions.
  </Card>

  <Card title="Multi-clip" icon="film" href="/agent-skills/multi-clip">
    Consistent characters and palette across a sequence.
  </Card>

  <Card title="Cost-aware" icon="shield-halved" href="/agent-skills/cost-aware">
    Budget guardrails for autonomous loops.
  </Card>

  <Card title="Author your own" icon="pen-nib" href="/agent-skills/authoring">
    Write a custom skill for your use case.
  </Card>
</CardGroup>

## Installing a skill

Skills are platform-specific. The same skill text gets loaded in
slightly different ways:

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    # 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.
  </Tab>

  <Tab title="Claude Desktop">
    Claude Desktop doesn't have a first-class skill loader yet. Until
    it does, paste the skill body into a project's *Custom
    Instructions* field or into your message preamble.

    See each skill page for a copy-paste version of its body.
  </Tab>

  <Tab title="Cursor">
    Add skill text as a project rule in `.cursor/rules/lavendly.md`.
    Composer reads project rules automatically.
  </Tab>

  <Tab title="Custom runtime">
    Concatenate the skill body into your system prompt before passing
    the MCP tool catalog. See [Anthropic SDK pattern](/sdks/anthropic-sdk)
    for an end-to-end example.
  </Tab>
</Tabs>

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

<Steps>
  <Step title="`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`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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*.
  </Step>
</Steps>

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:

```js theme={null}
const system = [
  baseSystem,
  loadSkill('cost-aware'),    // priority: high, applies globally
  loadSkill('storyteller'),   // priority: normal, domain choices
].join('\n\n');
```

Or in Python:

```python theme={null}
from lavendly.skills import load_many
system = base_system + "\n\n" + load_many(["cost-aware", "storyteller"])
```

### Conflict resolution at a glance

| Disagreement                                                                   | Winner                                      |
| ------------------------------------------------------------------------------ | ------------------------------------------- |
| `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 moods                          | Last 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.