Writing Docs
Guides for writing and editing Remotion documentation. Use when adding docs pages, editing MDX files in packages/docs, or writing documentation content.
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Writing Docs when an AI agent needs a reusable SKILL.md workflow for this job: Guides for writing and editing Remotion documentation. Use when adding docs pages, editing MDX files in packages/docs, or writing documentation content.
When not to use it
Skip Writing Docs when the task is outside the writing category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/writing-docs # Save SKILL.md to ~/.claude/skills/writing-docs/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/writing-docs/SKILL.md. For a shared project, commit the folder at .claude/skills/writing-docs/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Writing Docs skill for this task: Use Writing Docs when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
70/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 76/100
- Practical detail
- 68/100
- Source evidence
- 63/100
- Source signals
- 70/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# Writing Remotion Documentation
Documentation lives in `packages/docs/docs` as `.mdx` files.
## Adding a new page
1. Create a new `.mdx` file in `packages/docs/docs` 2. Add the document to `packages/docs/sidebars.ts` 3. Write the content following guidelines below 4. Run `bun render-cards.ts` in `packages/docs` to generate social preview cards
**Breadcrumb (`crumb`)**: If a documentation page belongs to a package, add `crumb: '@remotion/package-name'` to the frontmatter. This displays the package name as a breadcrumb above the title.
```md --- image: https://remotion.media/docs/generated/articles-docs-my-package-my-api.png title: '<MyComponent>' crumb: '@remotion/my-package' --- ```
**One API per page**: Each function or API should have its own dedicated documentation page. Do not combine multiple APIs (e.g., `getEncodableVideoCodecs()` and `getEncodableAudioCodecs()`) on a single page.
**Public API only**: Documentation is for public APIs only. Do not mention, reference, or compare against internal/private APIs or implementation details.
**API names in prose**: Put API names in backticks, and link them if a docs page exists. Function and hook names should include `()`, for example [`useVideoConfig()`](/docs/use-video-config), not `useVideoConfig` or useVideoConfig. Components should include angle brackets, for example [`<Player>`](/docs/player/player) or [`<Audio>`](/docs/media/audio).
**Use headings for all fields**: When documenting API options or return values, each property should be its own heading. Use `###` for top-level properties and `####` for nested properties within an options object. Do not use bullet points for individual fields.
**Version indicators**: If an API, feature, parameter, or behavior was added in a specific version, add `<AvailableFrom>` at the page, section, or field where the reader first needs to know it. For example: `# prefetch()<AvailableFrom v="4.0.0" />`.
**Compatibility tables**: API pages should ideally include a `## Compatibility` section with `<CompatibilityTable>` before `## See also`.
**Sidebar order**: When adding or moving docs in `packages/docs/sidebars.ts`, inspect the surrounding entries and match the ordering logic already used there. If a section is alphabetical, place the new entry alphabetically; if it is grouped by workflow or importance, place it consistently with that grouping. Do not leave new additions as one-off outliers.
## Language guidelines
- **Keep it brief**: Developers don't like to read. Extra words cause information loss. - **Link to terminology**: Use [terminology](/docs/terminology) page for Remotion-specific terms. - **Do not bold terms**: Write terms as plain text, code spans, or links as appropriate. Do not use bold formatting to introduce a term. - **Avoid emotions**: Remove filler like "Great! Let's move on..." - it adds no information. - **Separate into paragraphs**: Break up long sections. - **Address as "you"**: Not "we". - **Don't blame the user**: Say "The input is invalid" not "You provided wrong input". - **Don't assume it's easy**: Avoid "simply" and "just" - beginners may struggle.
## Code snippets
Basic syntax highlighting:
````md ```ts const x = 1; ``` ````
### Type-safe snippets (preferred)
Use `twoslash` to check snippets against TypeScript:
````md ```ts twoslash import {useCurrentFrame} from 'remotion'; const frame = useCurrentFrame(); ``` ````
### Hiding imports
Use `// ---cut---` to hide setup code - only content below is displayed:
````md ```ts twoslash import {useCurrentFrame} from 'remotion'; // ---cut--- const frame = useCurrentFrame(); ``` ````
### Adding titles
Always add a `title` to code fences that show example usage:
````md ```ts twoslash title="MyComponent.tsx" console.log('Hello'); ``` ````
## Special components
### Steps
Keep one `<Step>` per line and add a space after `</Step>`. Use an explicit line break (`<br/>` or `<br />`) when consecutive steps should appear on separate lines. Do not add Markdown bullet markers solely to wrap steps in a `<ul>`.
```md <Step>1</Step> First step<br /> <Step>2</Step> Second step ```
### Experimental badge
```md <ExperimentalBadge> <p>This feature is experimental.</p> </ExperimentalBadge> ```
### Interactive demos
```md <Demo type="rect"/> ```
Demos must be implemented in `packages/docs/components/demos/index.tsx`. See the `docs-demo` skill for details on adding new demos.
### AvailableFrom
Use to indicate when a feature or parameter was added. No import needed - it's globally available.
**For page-level version indicators**, use an `# h1` heading with `<AvailableFrom>` inline so it appears next to the title (not below it). Use `<` and `>` to escape angle brackets in component names:
```md # <MyComponent><AvailableFrom v="4.0.123" /> ```
```md # @remotion/my-package<AvailableFrom v="4.0.123" /> ```
For section headings:
```md ## Saving to another cloud<AvailableFrom v="3.2.23" /> ```
### CompatibilityTable
Use to indicate which runtimes and environments a component or API supports. No import needed. Place it in a `## Compatibility` section before `## See also`.
Available boolean props: `chrome`, `firefox`, `safari`, `player`, `studio`, `clientSideRendering`, `serverSideRendering`. Set to `true` (supported) or `{false}` (not supported).
Set to empty string `""` for not applicable if this is a frontend API: `nodejs=""`, `bun=""`, `serverlessFunctions=""`. Use `hideServers` to hide the Node.js/Bun/serverless row if this is a frontend API.
```md ## Compatibility
<CompatibilityTable chrome firefox safari nodejs="" bun="" serverlessFunctions="" clientSideRendering={false} serverSideRendering player studio hideServers /> ```
### Optional parameters
For optional parameters in API documentation:
1. **Add `?` to the heading** - this indicates the parameter is optional --> Don't do it if it is a CLI flag (beginning with `--`) - CLI flags are always optional 2. **Do NOT add `_optional_` text** - the `?` suffix is sufficient 3. **Include default value in description** - mention it naturally in the text
```md ### onError?
Called when an error occurs. Default: errors are thrown. ```
**Do NOT do this:**
```md ### onError?
_optional_
Called when an error occurs. ```
### Combining optional and AvailableFrom
When a parameter is both optional and was added in a specific version:
```md ### onError?<AvailableFrom v="4.0.50" />
Called when an error occurs. ```
### "Optional since" pattern
If a parameter became optional in a specific version (was previously required):
```md ### codec?
Optional since <AvailableFrom v="5.0.0" inline />. Previously required. ```
## Generating preview cards
After adding or editing a page, generate social media preview cards:
```bash cd packages/docs && bun render-cards.ts ```
The command uploads cards to `https://remotion.media/docs/generated/` and requires R2 credentials from the docs environment or `bun --env-file`. Commit the hosted `image:` frontmatter; local generated PNGs are ignored. To replace an existing card, pass `--overwrite=<composition-id>`.
## Streamlining existing docs
When asked to audit or streamline docs, scan for:
- Missing `<AvailableFrom>` indicators for APIs, features, options, parameters, or behaviors introduced in a specific version - API names that are not formatted as code spans or linked to their docs page - Function and hook references missing `()` - API pages that should have a `## Compatibility` section with `<CompatibilityTable>` - Fragile or broken `<Step>` formatting
Intended uses
- Use Writing Docs when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.