writing-docs

Guides for writing and editing Remotion documentation. Use when adding docs pages, editing MDX files in packages/docs, or writing documentation content.

Quality

90%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

93%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A concise, highly actionable skills body with concrete examples and a clear page-creation workflow. Adding an explicit verification/rebuild feedback loop and splitting detailed component references into separate files would push it to the top level.

Suggestions

Add an explicit validate→fix→retry loop after `bun render-cards.ts` (e.g. 'confirm the card rendered for the new page; if missing, re-run') to satisfy the workflow_clarity feedback-loop expectation.

Consider extracting the detailed special-component props (CompatibilityTable, AvailableFrom variants) into a reference file in references/ and linking to it, so progressive_disclosure hits the one-level-deep ideal.

Dimension	Reasoning	Score
Conciseness	Lean bullet-driven prose that assumes Claude's competence; code examples carry the weight and every line earns its place with no padding about what docs or MDX are.	5 / 5
Actionability	Copy-paste-ready md/bash code fences throughout, plus explicit do/don't blocks (e.g. the 'Optional parameters' section) that make the guidance fully executable.	5 / 5
Workflow Clarity	'Adding a new page' is a clear numbered sequence ending in a rebuild step, and 'Streamlining existing docs' gives a concrete audit checklist, but there is no explicit validate→fix→retry feedback loop around the rebuild.	4 / 5
Progressive Disclosure	A single well-organized file with clear sections and one-level-deep cross-reference to the 'docs-demo' skill; with no bundle files provided, structure is solid but not the canonical multi-file split of a 5.	4 / 5
	Total	18 / 20 Passed

Description

86%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong, well-scoped description that answers both what and when with concrete, project-specific triggers. Minor gains possible from adding a few more synonyms or file extensions in the trigger clause.

Dimension	Reasoning	Score
Specificity	Names the domain and lists several concrete actions — 'writing and editing', 'adding docs pages', 'editing MDX files' — but coverage of editing sub-tasks is slightly less comprehensive than a 5.	4 / 5
Completeness	Explicitly states what ('Guides for writing and editing Remotion documentation') and when ('Use when adding docs pages, editing MDX files...') with concrete trigger phrases.	5 / 5
Trigger Term Quality	Good natural keywords users would say ('docs pages', 'MDX files', 'writing documentation content') with the path 'packages/docs', though a few synonyms or extensions are missing.	4 / 5
Distinctiveness Conflict Risk	Scoped to Remotion documentation with project-specific triggers like 'MDX files in packages/docs', giving it a clear niche with minimal conflict risk.	5 / 5
	Total	18 / 20 Passed

Validation

93%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 4 suspicious	Warning

	Total	15 / 16 Passed

Repository: remotion-dev/remotion
Path: .agents/skills/writing-docs/SKILL.md
Commit: 77354de

Reviewed: about 21 hours ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.