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

# Custom Skills

> Add your own skills to extend the agent's capabilities per project

# Custom Skills

Each project can have custom skills — packaged `.zip` bundles you upload through the web UI. They're loaded alongside the built-in skills whenever the agent runs.

## Getting started

1. Navigate to **Brand Assets** in your project dashboard
2. Click **Custom Skills** in the sidebar
3. Click **+ New skill**, pick a slug, and upload a `.zip` containing `SKILL.md`

## Skill package layout

Inside the zip:

```
my-skill.zip
  SKILL.md             # Required — skill definition (at the zip root)
  rules/               # Optional — additional reference files
    some-rule.md
    another-rule.md
```

The only required file is `SKILL.md` at the root of the zip.

## Writing a SKILL.md

A skill file has two parts: **frontmatter** (metadata) and **body** (instructions for the agent).

```markdown theme={null}
---
name: my-skill
description: Short description of what this skill does.
metadata:
  tags: tag1, tag2
---

# My Skill

Instructions for the agent when this skill is activated.

## When to use

Describe the situations where this skill applies.

## How to use

Step-by-step guidance for the agent.
```

### Frontmatter fields

| Field           | Required | Description                                              |
| --------------- | -------- | -------------------------------------------------------- |
| `name`          | Yes      | Unique identifier (kebab-case, e.g. `my-skill`)          |
| `description`   | Yes      | One-line summary — used to decide when to load the skill |
| `metadata.tags` | No       | Comma-separated tags for categorization                  |

### Body

The body is free-form Markdown. Write it as if you're briefing a colleague — the agent reads these instructions when the skill is relevant to the current task.

Common sections to include:

* **When to use** — triggers and scenarios
* **How to use** — step-by-step patterns
* **Rules** — constraints, gotchas, things to avoid
* **Examples** — sample prompts or code snippets

## Adding reference files

For complex skills, break additional context into separate files under a `rules/` subdirectory and reference them from `SKILL.md`:

```markdown theme={null}
## Database queries

When writing database queries, load the [./rules/queries.md](./rules/queries.md)
file for detailed patterns and examples.
```

This keeps the main skill file scannable while allowing deep-dive content when needed.

## Example: brand voice skill

```
skills/
  brand-voice/
    SKILL.md
```

```markdown theme={null}
---
name: brand-voice
description: Enforces brand tone, vocabulary, and messaging guidelines for all copy.
metadata:
  tags: copywriting, brand, tone
---

# Brand Voice

Apply these guidelines whenever writing ad copy, landing pages, or any
user-facing text.

## Tone

- Conversational but confident
- Short sentences, active voice
- No jargon — explain benefits, not features

## Vocabulary

Always use:
- "Get started" (not "Sign up")
- "Free trial" (not "Freemium")
- "Your app" (not "The application")

## Avoid

- Exclamation marks in headlines
- Superlatives ("best", "fastest") without proof points
- Generic CTAs ("Click here", "Learn more")
```

## Reserved skill names

Some skill names have special meaning — the agent's built-in workflows look for them by name. If you create a skill with a reserved name, it plugs directly into the corresponding pipeline.

### `content-lookup`

The video assembly pipeline uses this skill to discover source video content. When the agent needs raw footage for clip selection, it invokes `content-lookup` to get a list of available content entries with preview URLs.

Your `content-lookup` skill should return structured information about where to find source videos — for example, an API endpoint, a folder path, or a catalog of entries with URLs the agent can fetch.

```markdown theme={null}
---
name: content-lookup
description: Returns available source video content for clip selection and assembly.
metadata:
  tags: video, content, source
---

# Content Lookup

Use this skill to find source video content for ad assembly.

## Available content

| Name | Preview URL | Duration | Notes |
|------|------------|----------|-------|
| App walkthrough | https://example.com/videos/walkthrough.mp4 | 45s | Main product demo |
| User testimonial | https://example.com/videos/testimonial.mp4 | 30s | Social proof clip |
| Feature highlight | https://example.com/videos/feature.mp4 | 20s | Key feature demo |
```

<Tip>
  Without a `content-lookup` skill, the agent won't know where to find source footage for video assembly. Add this skill first if you're producing video ads.
</Tip>

## Updating skills

Re-upload the skill using the same slug — the new zip replaces the old one.
The agent picks up changes on the next sync (automatic on sandbox wake, or
trigger manually with the `sync_skills` tool during a session).

## Built-in skills

Your custom skills run alongside the built-in skills that ship with the agent. These include skills for Remotion video production, ElevenLabs voice synthesis, video assembly, frontend design, and more. Custom skills take the same format and have equal priority.