Contributing Guide: AI Skills Workflow & Guidelines

Welcome to the Mujin Gemba Walk Contributing Guide!

This site serves as the public “Wikipedia” and sourcing tool for our recruiting team (Talent Acquisition) and prospective candidates. It provides deep, authentic insights into our engineering teams, culture, and technology.

To keep documentation accurate, rich, and effortless to update, we use a Skills-First Workflow. You can update any team page, team blog post, or guide in minutes by instructing your preferred AI coding assistant (Cursor, Antigravity, Claude Code, Copilot, ChatGPT, etc.) using our repository’s AI Skill manifests.

---

🤖 AI Skills-First Workflow (Standard Method)

The quickest and recommended way to contribute is to let an AI assistant handle the Markdown syntax, frontmatter schema validation, and bilingual translation.

We maintain curated AI Skill definitions under the skills/ directory.

1. Open the Project in Your AI Editor / Assistant

   Open this repository in your preferred AI coding environment (Cursor, Antigravity, Zed, Claude Code, etc.) or copy the skill file into your AI Web UI system prompt.

2. Load the Relevant AI Skill

   Direct your AI assistant to read the target skill definition:

   • For Team Profiles: Point it to skills/team-page-builder.md
   • For Team Blog Posts: Point it to skills/blog-post-builder.md

3. Request Updates in Plain Language

   Ask the AI to create or update content. For example:

   “Please use skills/team-page-builder.md to update our DevOps Team profile. We are adopting OpenTelemetry and ArgoCD, and we want to add ‘cloud-native observability’ as a core success trait.”

   “Please use skills/blog-post-builder.md to write a new engineering blog post about our 60fps WebGL viewport for Mujin OS.”

4. Review Bilingual Outputs

   The AI Skill automatically enforces:

   • AEO Metadata: Ensures description, techStack, and successTraits are present.
   • Bilingual Parity: Drafts the English page (src/content/docs/blog/... or teams/...) and automatically synchronizes the Japanese page (src/content/docs/ja/...).
   • Component Formatting: Renders responsibilities in <CardGrid> and workflows in <Steps>.

5. Commit and Push

   Review the generated files locally, then stage, commit, and push your branch to open a Pull Request!

---

🛡️ Multi-AI Automated Safeguards (Pre-commit Hooks)

Regardless of which AI coding tool or LLM model you or your team members use, our repository enforces automated pre-commit safeguards:

• pnpm okf:sync: Auto-injects missing type frontmatter tags across all MDX documents.
• pnpm generate:llms: Validates required AEO metadata (techStack, description, successTraits) and updates public LLM indices (/llms.txt).
• pnpm i18n:check: Audits document pairs and warns if Japanese or English pages are missing.

When you run git commit, these hooks execute automatically via simple-git-hooks and lint-staged to guarantee repository consistency.

---

🖥️ Manual & Keystatic CMS Workflow (Alternative)

If you prefer to edit content manually or use a graphical web editor without AI assistance, you can use Keystatic CMS:

1. Clone the repository and install dependencies using pnpm:

   pnpm install

2. Start the development server and Keystatic UI:

   pnpm dev

3. Open http://localhost:4321/keystatic in your browser to edit English and Japanese collections visually (Team Pages, Blog Posts, Benefits).
4. Save your changes and commit the modified .mdx files via Git.

---

📝 Writing Standards & AI Search Optimization (AEO)

Candidates and AI search engines (like Perplexity, ChatGPT, and Gemini) rely on this site to retrieve factual information about Mujin. When writing or editing, please follow these guidelines:

BLUF (Brevity-First)

Provide a concise 1-2 sentence mission summary in the frontmatter description field. The site automatically renders this description inside a styled Quick Answer banner at the top of the page body.

Factual & Technical

Include specific details about your stack, tools, and real-world system challenges (e.g., C++17/20, motion planning, digital twin latency limits, RTOS configurations).

Bilingual Parity

Keep English and Japanese pages synchronized. Loading skills/team-page-builder.md or skills/blog-post-builder.md handles this translation automatically!

Clean Design System

Rely on built-in design system components (<CardGrid>, <Steps>, <LinkCard>) rather than manual inline styling or custom HTML tags.

---

Need Help?

If you have questions about using AI Skills or want to propose a new Skill definition, please reach out to the Engineering Enablement / Frontend System Team or open an issue on the repository.