Claude Code Skill

The /ambasdr-docs Skill

Scaffolds, authors, and maintains documentation artifacts in the Ambasdr diorama-docs/ directory. Handles Docusaurus sync, naming conventions, and styling consistency so every doc page matches the existing site.

What It Does

The /ambasdr-docs skill manages the documentation site at diorama-docs/. It knows the styling system (shared.css), the page component grammar (hero, numbered sections, cards, callouts, steps, tables), and the Docusaurus integration layer. When you ask to add or update documentation, it handles the full pipeline: create the HTML, sync to Docusaurus static assets, write the MDX wrapper, and verify the build.

Scaffold

Quick Start

Generates a new HTML page with the correct tokens, back link, hero, and section skeleton already wired up.

Author

Full Pages

Composes multi-section documentation using the page component grammar: cards, callouts, steps, tables, code blocks.

Sync

Docusaurus

Copies HTML to static assets, creates MDX iframe wrappers, verifies the Docusaurus build passes.

How to Use

Invoke from Claude Code when you need to add or update documentation.

Trigger Phrases

"add docs", "create documentation", "write an explainer", "add to diorama-docs", "scaffold a doc", "document this", "add an instructional", "update the docs site".

Describe what you need

Tell Claude what documentation to create: "document the auth flow", "add an explainer for the token package", "scaffold docs for the voice agent".

Confirm the topic folder

The skill proposes a kebab-case folder name under diorama-docs/. Confirm or adjust.

Review the output

The skill creates the HTML artifact, syncs Docusaurus, and stages all files. Review the diff before pushing.

Scaffolder Script

For quick starts, the skill includes a scaffolder that generates a stub page with the correct styling:

# Scaffold a new topic
python3 .claude/skills/ambasdr-docs/scripts/new-artifact.py \
  diorama-docs/auth-flow "Authentication Flow"
# -> creates diorama-docs/auth-flow/index.html

# Scaffold a companion page
python3 .claude/skills/ambasdr-docs/scripts/new-artifact.py \
  diorama-docs/auth-flow/data-model.html "Auth Data Model"

Docusaurus Sync

Every new HTML artifact needs three things to appear in the docs site:

Copy to static

Run python3 diorama-docs/tools/sync-static-html.py or manually copy the HTML into website/static/html/.

Create MDX wrapper

Add an MDX file in website/docs/ that imports HtmlEmbed and points at the static HTML path.

Verify build

Run cd diorama-docs/website && npx docusaurus build --no-minify and confirm no errors.

Styling System

All pages link to shared.css rather than inlining tokens. The stylesheet provides:

Design Tokens

CSS custom properties for colors (--accent, --text, --border), shadows, and surfaces.

Page Components

Hero, numbered sections, cards with tones, callouts, numbered steps, decision tables, code blocks, plain lists.

Typography

Inter for body text, JetBrains Mono for code and section numbers. Loaded from Google Fonts.

Responsive

Mobile breakpoint at 760px. Page container collapses padding, grids stack to single column.

Skill Files

File	Purpose
`SKILL.md`	Main skill definition — workflows, Docusaurus sync process, naming conventions, content rules.
`brand-tokens.md`	CSS custom properties, typography scale, geometry rules, anti-patterns.
`page-components.md`	HTML snippets for every component: hero, sections, cards, callouts, steps, tables, code blocks.
`naming-conventions.md`	kebab-case rules, folder structure, canonical vs companion files, date conventions.
`scripts/new-artifact.py`	Scaffolder script — generates a stub HTML page with correct styling and back link.

The skill lives at .claude/skills/ambasdr-docs/ in the repository root.