Skip to content

OffchainLabs/arbitrum-docs / .agents/skills/new-doc

new-doc

Verified

Scaffold 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).

FieldExampleNotes
Title"Bridge tokens to Arbitrum"Sentence case, appears as H1. Required.
Descriptionone-sentence summaryRequired.
Sectionbuild-decentralized-appsMust 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 to title if omitted
  • content_type: one of how-to, concept, quickstart, tutorial, reference, troubleshooting, faq; an editorial label, nothing renders it
  • author: GitHub username
  • sme: subject matter expert GitHub username (can be same as author)
  • target_audience: intended readers and their assumed knowledge
  • user_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 thisNot this
Parent chain / Child chainL1/L2, Layer 1/Layer 2
appdapp, dApp
onchainon-chain
cross-chaincrosschain
Rolluprollup
AnyTrustanytrust
ERC-20, ERC-721ERC20
allowlist/denylistwhitelist/blacklist
bondstake (for proposing)
Your Arbitrum chainL3 Orbit chain

Post-creation checklist

After creating the file:

  1. Verify the sidebar entry and the page render: pnpm dev, then browse http://localhost:3000/{section}/{slug}. Use localhost, not 127.0.0.1 — on 127.0.0.1 React does not hydrate and every component looks broken.
  2. Run pnpm lint and pnpm types:check. Rule docs/frontmatter-schema validates every page against lib/page-schema.ts: a missing title or description fails this gate (the other fields are optional). types:check regenerates the collection and checks TypeScript; it does not validate every page's frontmatter.
  3. Confirm no broken links: pnpm check-links. It also validates #anchor fragments against the compiled heading ids; only anchors that exist at runtime alone are outside its reach.
  4. To reference a global variable, use <Var name="variableName" />; the value must exist in content/vars.json. Verify with pnpm vars:check.
  5. 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.
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: 465kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexUnverifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall