Prompt Library

These prompts are designed for use with AI tools (Claude, Copilot, Cursor, Gemini, etc.) when working on MediaKind documentation. Each prompt loads the context the AI needs and tells it exactly what to produce.

Before using any prompt: make sure the AGENTS.md file is loaded into your AI tool's context. If your tool does not auto-discover it from the repo root, add this line to the start of your prompt:

Read the AGENTS.md file at the repository root before doing anything. Follow it as your style and formatting guide.

Write a new page

Use these prompts when you have raw technical content and need a finished docs page.

Use for task-based pages: anything the reader needs to accomplish step by step.

Using AGENTS.md as your style and formatting guide, write a how-to page at the path below.

File path: pages/<product>/<section>/<page-name>.mdx
Topic: [What task does this page help the reader complete?]
Product: [MK.IO or MK.IO Beam]
Audience: [Developers / Video engineers / Administrators]
Why this matters: [What is the reader trying to achieve? What breaks if they skip this?]

Source material:
[Paste your raw notes, bullet points, or draft here]

Requirements:
- Valid frontmatter with title (7 words max) and description (one search-snippet sentence)
- H1 matching the title, blank line, then a 1–3 sentence intro for a reader arriving from search
- Prerequisites section if anything must be done first
- Numbered steps. Use <Steps> if any step contains a code block, screenshot, or sub-instructions. Use a plain numbered list for simple sequences.
- Prose before every code block (what it does) and after (field explanations, constraints, optional params)
- <RelatedTopics> at the end only if there is a direct next step
- List any orienting context you added under "Editorial additions"
- Flag any gaps or missing information at the end

Update an existing page

Use these prompts when a page already exists but needs changes.

Use when a page is technically accurate but does not meet the style guide. Applies the full editorial treatment without changing the technical content.

Using AGENTS.md as your style and formatting guide, apply a full editorial pass to the page below.

Do not change any technical content. Improve only how it is written and structured.

What to fix:
- Restructure for logical flow: prerequisites before steps, steps before verification
- Rewrite sentences for clarity, active voice, and 10–20 word target length
- Convert action paragraphs to numbered lists or <Steps> blocks
- Add the correct page opening (H1, blank line, intro) if missing
- Add prose before and after code blocks if missing
- Fix formatting: heading levels, bold, backticks, code block language tags
- Replace em dashes with hyphens, colons, or separate sentences
- Remove contractions and filler words
- Add or remove components where they genuinely help or are decorative

Page content:
[Paste the full page here]

At the end, list:
1. Structural changes you made and why
2. Any orienting context you added ("Editorial additions")
3. Any technical gaps or concerns for the contributor

Review and quality checks

Use these prompts to catch problems before merging a PR.

Use to check a page against the style guide before approving a PR.

Using AGENTS.md as your style and formatting guide, review the page below for style and formatting issues only. Do not suggest technical changes.

Report:
- Any em dashes (should be hyphens or colons)
- Any contractions (should be expanded: "don't" → "do not")
- Any filler words ("simply", "just", "easily", "please", "obviously")
- Any passive voice that should be active
- Any code blocks missing a language tag
- Any code blocks missing prose before or after
- Any code blocks prefixed with $ or >
- Any heading levels that skip a level
- Any numbered lists used where bullets should be (non-sequential items)
- Any bullet lists used where steps should be numbered (sequential actions)
- Any callouts that are decorative or restate something already in the prose
- Any components missing blank lines before or after
- Any internal links that include .mdx in the path
- Any missing or weak alt text on images

Page content:
[Paste the page here]

Maintenance tasks

Use these prompts for larger structural work across the docs.

Use when a page has grown too long and covers multiple distinct tasks.

Using AGENTS.md as your style and formatting guide, review the page below and recommend how to split it.

For each proposed split, specify:
- Which H2 sections would move to a new page
- The file path for the new page (following the existing folder structure)
- Why the split helps the reader

Do not actually split the page yet — provide the recommendation only. The contributor must approve before you make structural changes that affect URLs and the sidebar.

Page content:
[Paste the full page here]

Tips for better results

Tip	Why it matters
Give the AI all the raw technical detail	The AI cannot look things up. The more information you provide, the better and more accurate the output.
Specify the file path	The AI uses the path to pick the correct product terminology (MK.IO vs Beam) and folder conventions.
State the content type	"This is a how-to" or "this is a reference page" tells the AI which structure to apply.
Review the intro	The AI writes an intro based on your source material. Check it accurately describes what the page covers.
Iterate on sections	Ask the AI to refine specific parts: "shorten the intro", "convert section 3 to a table", "add a warning callout for the delete step".
Check technical accuracy	The AI preserves your content but can misinterpret ambiguous phrasing. Always verify steps, parameter names, and code examples.

Using AI to Write Docs