Our review
This skill scaffolds, structures, and deploys a Docusaurus site for a textbook, with book-aware content and RAG-ready exports.
Strengths
- Generates a complete site structure with sidebar and navigation
- Preconfigures deployment to GitHub Pages or Vercel
- Ensures RAG compatibility via frontmatter and semantic headings
- Provides concrete examples for chapter creation and local testing
Limitations
- Requires prior knowledge of Docusaurus and Node.js
- Specific to Docusaurus, not adaptable to other static site generators
- Algolia search setup requires additional API keys
Use this skill to create a structured course or textbook website with automated deployment and retrieval-augmented generation (RAG) readiness.
Do not use it if you need a simple site or prefer another static site generator like MkDocs or GitBook.
Security analysis
CautionThe skill uses npm and shell commands to scaffold and deploy a Docusaurus site. While the instructions are legitimate and targeted at textbook creation, running npx and npm install inherently introduces risk from third-party packages. The file creation commands are safe in context but could be problematic if directory paths were user-controlled.
- •Runs npm/npx commands that install and execute third-party packages.
- •Instructs writing files to local filesystem, which could be misused if paths are manipulated.
- •Includes script examples that execute shell commands, though benign as written.
Examples
Create a new chapter in the Physical AI book Docusaurus site for module 1 week 1. Add an intro.mdx file with frontmatter including title, description, module, week, and tags. The content should be an introduction to Physical AI.Build the Docusaurus site and serve it locally to verify the sidebar and content render correctly. Run the build command and then serve.Set up GitHub Actions workflow to deploy the Docusaurus site to GitHub Pages. Ensure the workflow runs npm ci, npm run build, and npm run deploy.name: book-docusaurus description: Scaffold, structure, and deploy the Physical AI textbook in Docusaurus with book-aware content and RAG-ready exports. Use when creating or updating the Docusaurus site, adding chapters, configuring sidebar, or deploying to GitHub Pages/Vercel.
Book Docusaurus Skill
Instructions
-
Scaffold the site
- Ensure Node >=18 is installed
- Run
npx create-docusaurus@latest physical-ai-book classicin project root or/docs - Configure
docusaurus.config.jswith site metadata, GitHub Pages URLs, i18n (en default)
-
Structure content
- Build
sidebars.jsfor Quarter overview, Modules 1-4, Capstone, Assessments, Hardware kits, Cloud option - Create MDX stubs per module/week with learning outcomes and tasks
- Add capstone outline
- Build
-
Authoring affordances
- Add MDX components for callouts, checklists, hardware tables, code blocks
- Enable search (Algolia DocSearch placeholder) and local search plugin for dev
-
Deploy
- Add GitHub Actions workflow for GH Pages (
npm ci,npm run build,npm run deploy) - Document Vercel deploy steps (import repo, build command
npm run build, outputbuild)
- Add GitHub Actions workflow for GH Pages (
-
RAG-readiness
- Enforce frontmatter fields:
title,description,module,week,tags - Keep headings semantic (h2 for weeks, h3 for sections)
- Avoid heavy client-side rendering for core text
- Export ingestion guidance: markdown path glob, ignore build/static
- Enforce frontmatter fields:
Examples
# Create new chapter
mkdir -p docs/module-1/week-1
cat > docs/module-1/week-1/intro.mdx << 'EOF'
---
title: Introduction to Physical AI
description: Overview of embodied intelligence and humanoid robotics
module: 1
week: 1
tags: [physical-ai, robotics, introduction]
---
# Introduction to Physical AI
Content here...
EOF
# Build and test locally
npm run build
npm run serve
Definition of Done
npm run buildpasses; site renders outline and sample content- Sidebar matches course hierarchy; links valid
- GH Pages workflow present; deploy instructions written
- Content annotated with frontmatter and semantic headings suitable for chunking
API Documentation Generator
Documentation
Automatically generates OpenAPI/Swagger API documentation.
Technical Writer
Documentation
Writes clear technical documentation following top style guides.
Documentation Maintenance
Documentation
This skill provides a structured workflow for updating project documentation including CLAUDE.md, README, and CHANGELOG. It walks through phases like inventorying existing docs, analyzing git history for needed changes, optimizing for AI readability, and ensuring cross-document consistency. Use it when synchronizing documentation with code changes or improving documentation effectiveness for AI coding agents.