OffchainLabs/arbitrum-docs / .agents/skills/new-doc
new-doc
VerifiedScaffold a new documentation page with correct frontmatter, terminology, and sidebar registration. Triggers on "new doc", "create page", "add doc", "scaffold doc".
New Doc
Scaffold a new MDX documentation page following all project conventions.
Required input from user
Only title and description are required by the frontmatter schema
(arbitrumPageSchema in source.config.ts); everything else below is
optional and the page is valid without it. Still ask for a Section up
front, since it decides the file's path (it is not a frontmatter field).
| Field | Example | Notes |
|---|---|---|
| Title | "Bridge tokens to Arbitrum" | Sentence case, appears as H1. Required. |
| Description | one-sentence summary | Required. |
| Section | build-decentralized-apps | Must match an existing content/docs/ subdirectory. Not a frontmatter field. |
Optional (omit the key entirely if not provided, rather than leaving it blank):
sidebar_label: the page's name in the sidebar; defaults totitleif omittedcontent_type: one ofhow-to,concept,quickstart,tutorial,reference,troubleshooting,faq; an editorial label, nothing renders itauthor: GitHub usernamesme: subject matter expert GitHub username (can be same as author)target_audience: intended readers and their assumed knowledgeuser_story: the reader's goal, for example "As a chain operator, I want to rotate node keys so I can keep my chain secure"
Preserve existing target_audience and user_story values when editing a page. Neither renders
on the site. There is no draft field in this schema; never add it when scaffolding a page.
File creation
1. Determine file path
content/docs/{section}/{slug}.mdx
Slug: lowercase title, spaces to hyphens, no special chars. File names carry no ordering — the
sidebar order comes from meta.json in the same directory (step 4).
2. Write frontmatter + skeleton
---
title: '{title}'
description: '{description}'
sidebar_label: '{sidebar_label}'
content_type: '{content_type}'
author: '{author}'
sme: '{sme}'
---
{skeleton based on content_type}
Drop any of sidebar_label, content_type, author, sme the user did not give you rather than
writing an empty string: they are optional fields, not required-but-blank ones.
3. Content type skeletons
how-to:
This how-to guide will help you {goal}.
## Prerequisites
- Item 1
## Steps
### Step 1: {first step}
{instructions}
### Step 2: {second step}
{instructions}
## Next steps
- [Related doc](link)
concept:
{One-paragraph summary of the concept.}
## Overview
{Detailed explanation}
## How it works
{Technical details}
## Key takeaways
- Point 1
quickstart:
This quickstart will get you {outcome} in under {time}.
## Prerequisites
- Item 1
## 1. {First step}
## 2. {Second step}
## What's next?
reference:
## Overview
{Brief description of what this reference covers.}
## Parameters
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| | | |
troubleshooting:
## Symptoms
{What the user observes}
## Common causes
### Cause 1: {description}
**Solution:** {fix}
4. Register in the sidebar
Sidebar order is controlled per directory by meta.json, not by file names. Open
content/docs/{section}/meta.json and add the slug (file name, no extension) to pages:
{
"title": "Get started",
"pages": ["index", "arbitrum-introduction", "{slug}"]
}
Place it in logical order within the existing entries. A "..." entry means "everything else, in
file order", so a new page appears automatically wherever "..." sits — add it explicitly only when
it needs a specific position. To list a page that lives in another directory, use a relative path
entry such as "../other-dir/page". Never write a "[Label](/docs/path)" entry for a page in this
repo: it puts the page on two sidebar nodes and pnpm test fails.
Terminology enforcement
Before writing any content, apply these substitutions:
| Write this | Not this |
|---|---|
| Parent chain / Child chain | L1/L2, Layer 1/Layer 2 |
| app | dapp, dApp |
| onchain | on-chain |
| cross-chain | crosschain |
| Rollup | rollup |
| AnyTrust | anytrust |
ERC-20, ERC-721 | ERC20 |
| allowlist/denylist | whitelist/blacklist |
| bond | stake (for proposing) |
| Your Arbitrum chain | L3 Orbit chain |
Post-creation checklist
After creating the file:
- Verify the sidebar entry and the page render:
pnpm dev, then browsehttp://localhost:3000/{section}/{slug}. Uselocalhost, not127.0.0.1— on127.0.0.1React does not hydrate and every component looks broken. - Run
pnpm lintandpnpm types:check. Ruledocs/frontmatter-schemavalidates every page againstlib/page-schema.ts: a missingtitleordescriptionfails this gate (the other fields are optional).types:checkregenerates the collection and checks TypeScript; it does not validate every page's frontmatter. - Confirm no broken links:
pnpm check-links. It also validates#anchorfragments against the compiled heading ids; only anchors that exist at runtime alone are outside its reach. - To reference a global variable, use
<Var name="variableName" />; the value must exist incontent/vars.json. Verify withpnpm vars:check. - Before writing a banner, note or config table, browse
content/partials/(there is no catalog; the partials themselves are the index) and reuse an existing one instead of duplicating prose.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 465k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 196k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |