Rule Conventions

Defining Rules and Best Practices

Rule conventions provide the structural and linguistic framework for creating skills that an agent can interpret and apply. By following these conventions, you ensure that the agent provides consistent, high-quality code generation and validation.

File Structure and Metadata

Each rule is defined as a Markdown file within the .agent/skills/ directory. Files must begin with a YAML frontmatter block to allow the agent to index and retrieve relevant context based on the current task.

---
name: rule-name-kebab-case
description: A concise summary of what this rule covers.
metadata:
  tags: [tag1, tag2, tag3]
---

• name: A unique identifier for the rule.
• description: Used by the agent to determine if the rule is relevant to a user's prompt.
• tags: Keywords for categorizing domain-specific knowledge (e.g., 3d, audio, interpolation).

Mandatory Directives

Rules should use explicit, forceful language to define boundaries. This reduces ambiguity during code generation. Use the following keywords to signify priority:

• MUST / MUST NOT: Defines a non-negotiable requirement (e.g., "You MUST wrap 3D content in <ThreeCanvas>").
• FORBIDDEN: Explicitly bans specific patterns or libraries (e.g., "CSS transitions are FORBIDDEN").
• REQUIRED: Indicates a dependency or setup step that cannot be skipped.

Prerequisites and Dependencies

If a rule requires specific packages or environment configurations, list them at the beginning of the file. Provide the necessary commands for various package managers to ensure the agent can fix missing dependencies automatically.

## Prerequisites

The `@remotion/media` package is required.
```bash
npx remotion add @remotion/media

### Technical Code Examples

Code blocks are the primary method for communicating implementation details. When writing examples:

1.  **Use TypeScript**: Ensure all examples are type-safe to reflect the framework's best practices.
2.  **Highlight Key Logic**: Focus the example on the rule being explained (e.g., show the `interpolate` function when explaining animations).
3.  **Use Functional Components**: Favor modern React patterns unless documenting a legacy interface.
4.  **Provide Context**: If a specific composition size or frame rate is assumed, mention it as a comment.

```tsx
import { useCurrentFrame, interpolate } from "remotion";

// Example: Driving opacity via frame count
export const FadeIn = () => {
  const frame = useCurrentFrame();
  const opacity = interpolate(frame, [0, 20], [0, 1]);
 
  return <div style={{ opacity }}>Content</div>;
};

Handling Non-Deterministic Behavior

For frameworks like Remotion, where rendering must be deterministic, rules must explicitly prohibit APIs that rely on real-time clocks or browser-managed transitions.

• State Management: Instruct the agent to drive state via useCurrentFrame() or spring().
• Third-Party Libraries: Specify how to disable internal animations of external libraries (e.g., D3 or Three.js) so the agent can take control of the timeline.

Formatting and Organization

• H2 for Categories: Use Level 2 headings to group related concepts (e.g., ## Trimming, ## Volume).
• Lists for Guidelines: Use bulleted lists to provide quick-reference constraints.
• Relative Linking: When rules reference other rules or assets, use relative Markdown links: [See Bar Chart Example](assets/charts/bar-chart.tsx).

Example Rule Template

# [Rule Title]

[Brief explanation of the technical domain]

## Key Constraints

- **Directives**: (e.g., "All animations MUST be driven by `useCurrentFrame()`")
- **Prohibitions**: (e.g., "No `setTimeout` or `setInterval`")

## Usage

[Code example showing the public interface and expected props/types]

## Common Patterns

[Secondary examples or edge-case handling]