Defining Rules & Best Practices

Structure of a Rule Skill

Rule-based skills are collections of markdown files designed to provide an agent with domain-specific constraints and best practices. In the context of Remotion, these rules ensure the agent generates code that is compatible with the frame-based rendering engine.

A standard rule skill consists of a root SKILL.md file and a rules/ directory containing individual topic-based markdown files.

The Skill Index (SKILL.md)

The SKILL.md file acts as the entry point and manifest for the skill. It must include metadata to help the agent identify when to apply the rules.

• Name: A unique identifier (e.g., remotion-best-practices).
• Description: A high-level overview of what knowledge the skill provides.
• Metadata Tags: Keywords used for skill discovery.
• Rule Mapping: A list of links to specific rule files with brief descriptions of their contents.

---
name: skill-name
description: Brief description of the domain
metadata:
  tags: [tag1, tag2]
---

## When to use
Instructions for the agent on when this domain knowledge is applicable.

## How to use
- [rules/topic.md](rules/topic.md) - Description of the topic.

Anatomy of a Rule File

Each file in the rules/ directory should focus on a single, atomic topic (e.g., "Audio", "3D Content", or "Fonts"). This granularity allows the agent to retrieve only the relevant context for a specific task.

1. Frontmatter

Every rule file must start with a YAML frontmatter block to provide the agent with semantic context.

---
name: animations
description: Fundamental animation skills for Remotion
metadata:
  tags: [animations, transitions, frames]
---

2. Constraints and Enforcement

The core of the rule file should define clear "Must" and "Must Not" instructions. This prevents common errors in the target framework (e.g., using CSS transitions in Remotion which are incompatible with server-side rendering).

• Imperative Language: Use words like MUST, FORBIDDEN, or REQUIRED.
• Specific Context: Explain why a rule exists if it deviates from standard development patterns.

3. Code Examples

Provide "Ideal" implementation examples. Use TSX or JSX blocks to demonstrate the correct usage of the public API.

import { useCurrentFrame, interpolate } from "remotion";

// Animate using frame-based logic instead of CSS
const frame = useCurrentFrame();
const opacity = interpolate(frame, [0, 20], [0, 1]);

Writing Effective Rules

To maximize the agent's performance, follow these documentation patterns:

Use "Golden" Examples

When documenting complex components like charts or text effects, include a full, self-contained component example. Mark these as "Ideal composition size" or "Reference Implementation" to guide the agent toward tested patterns.

Identify Prerequisites

If a specific rule requires an external package (e.g., @remotion/media), include the installation command. This allows the agent to fix environment issues before writing code.

npx remotion add @remotion/media

Versioning and Compatibility

If a rule applies only to specific versions of a library or specific browsers, clearly state these limitations in the "Important Notes" or "Prerequisites" section.

Avoid Implementation Detail

Focus on the Public Interface. The agent needs to know how to use the components and functions, not how the internal state is managed within the library source code. Document:

• Input Props/Arguments and their types.
• Return values.
• Required wrapping components (e.g., wrapping 3D content in <ThreeCanvas>).

Organizing the Rules Directory

Maintain a flat or shallow directory structure within rules/. Group related functionality into single files rather than creating deep nested folders.

• Good: rules/assets.md (Covers images, video, and audio imports).
• Avoid: rules/assets/images/svg-handling.md (Too granular for efficient context loading).

If a rule requires a large code asset (like a complex React component used as a template), store it in a sub-directory named assets/ and link to it from the primary rule file.