Hugo Docs Structure Map: An Agent Skill for Safe Edits

Where this fits

A maintainer asks an agent to add a Getting Started link to the docs site. The agent opens data/menu/main.yaml, changes one locale, and misses that the Hugo site has four locale trees and defaultContentLanguage = "ko". This skill gives the agent a preloaded map of the exact paths, schemas, and invariants for the oss-docs harness at docs-site/, so navigation and config edits are safe before the first write.

Why agents benefit

• It knows hugo.toml is the only config filename, defaultContentLanguage = "ko", and params.version is the source of truth.
• It can read content/{ko,en,ja,zh}/_meta.yaml schemas and keep all four locale trees mirrored instead of guessing.
• It knows data/menu/main.yaml expects four-locale name maps plus icon values, and that layouts/partials/menu.html couples icon names to SVG cases.
• It treats moai-brand.css as FROZEN and avoids fixing it when brand styling looks inconsistent.
• It has vercel.json redirect examples, so a new redirect follows existing conventions.

Practical scenarios

Adding a navigation entry across four locales

The agent consults the structure map, finds data/menu/main.yaml, and updates the key under every locale name map while preserving icon values. The map also flags layouts/partials/menu.html icon coupling, so the agent validates the SVG case before finishing.

Creating a new page in the Chinese locale

Instead of inventing a front-matter schema, the agent uses the map to find content/zh/_meta.yaml, compares it to the canonical ko tree, and creates the mirror. It also knows not to touch hugo.toml unless a version bump requires it.

Debugging a missing menu icon

When the icon renders blank, the agent greps menu.html to see how icon keys map to SVG file names. Because the map names this coupling explicitly, it checks case-sensitivity and the FROZEN CSS rather than blindly adding a new icon library.

Add it to your agent workflow

Install with:

npx skills add modu-ai/moai-adk --skill hns-oss-docs-structure-map

Before an agent edits navigation or config on the docs site, have it load the map and read the relevant subsection. For example:

Read the structure-map skill, then read docs-site/data/menu/main.yaml. Verify all four locale name maps and icon values before proposing a change.

The skill is not user-invocable; the structure-curator loads it automatically, so you only need to keep the installation wired into that harness.

Compare before adopting

Before adding it, compare against a few things:

• Freshness: metadata says version 1.0.0, updated 2026-07-13, status active; check the repo history for how quickly structure changes are reflected.
• Alternatives: a generic Hugo skill or manual Grep/Read workflow can work, but you will re-discover the locale and CSS constraints each time.
• Fit: if your docs site is not the geekdoc-based oss-docs harness, many paths and schemas will not apply.
• Workflow fit: it is most useful when structure-curator already runs before any docs-site edit.

Why it is worth tracking

This skill encodes hard-won constraints that cause silent, time-consuming errors: locale mirroring, icon-to-SVG case coupling, and the FROZEN brand CSS. The repo's 1,195 stars and active harness category suggest it is maintained around a real deployment. You can track it in the OpenAgentSkill directory at https://www.openagentskill.com/skills/modu-ai-hns-oss-docs-structure-map to see metadata, version updates, and community signals. Re-evaluate when the docs site upgrades Hugo, changes locales, or splits the design and guides trees.