Hugo Expert
Deep help with Hugo static sites. This skill carries durable Hugo best-practices and pins live
documentation lookups to the repo's actual Hugo version — Hugo ships frequently and APIs change, so
verify current syntax against the docs rather than from memory.
Preflight — live docs via find-docs
Current Hugo syntax, template functions, and config keys are fetched with the find-docs skill
(Context7). Confirm it's available (it appears in your available skills); if it's missing, tell the
user and offer to install it — npx skills find find-docs. Without it, say so and proceed from
general knowledge, flagging that version-specific details may be stale.
1. Detect the target version
Run the detector at the repo root to pin doc lookups to the right version:
"<skill-dir>/scripts/detect_hugo.py" .
It reports the config file/format, the pinned Hugo version, Hugo Modules usage, an
extended-vs-standard hint, and configured themes. For a brand-new repo (is_new_repo), use the
latest Hugo release — look it up (hugo version, the GitHub releases page, or Context7); never
assume a hardcoded version.
2. Fetch current docs when it matters
Before asserting exact template-function signatures, config keys, or version-specific behavior, use
the find-docs skill to pull the current Hugo docs (library Hugo → /gohugoio/hugo). Query one
specific topic at a time, and pin the repo's version when it declares one. Rely on the references
below for durable practice; reach for live docs when the detail is version-sensitive.
3. Route to the reference for the task
Read only the file(s) the task needs:
| Task |
Reference |
| Go templates, partials, blocks, render hooks, lookup order |
references/templating.md |
| Creating/customizing a theme, overriding, publishing |
references/themes.md |
| Sections, page/leaf bundles, taxonomies, front matter, archetypes |
references/content-modeling.md |
hugo.toml/environments, Hugo Modules, mounts |
references/config-modules.md |
| Hugo Pipes, image processing, minify/fingerprint, caching |
references/performance.md |
Netlify/Vercel/Pages, CI, HUGO_VERSION, baseURL |
references/deployment.md |
| Version bumps, deprecations, extended vs standard |
references/upgrade-migration.md |
| Multilingual sites, translations |
references/i18n.md |
| Sitemap, RSS/output formats, meta/OpenGraph, structured data |
references/seo-feeds.md |
4. Best-practice bar (holds across versions)
- Prefer configuration over hardcoding; keep environment-specific values in
config/<env>/.
- Build themes as Hugo Modules over copying files; override by shadowing layouts in the project.
- Compose layouts from partials and render hooks; don't duplicate markup across templates.
- Route CSS/JS/images through the asset pipeline (Hugo Pipes) — fingerprint and minify for production.
- Pin
HUGO_VERSION in CI/deploy so local and production builds match.
- Verify with
hugo server during work and a clean hugo --minify before shipping; treat build
warnings and deprecations as work to resolve.
5. Writing blog posts → delegate
To write a blog post in the author's established voice, use the hugo-write-post skill rather than
drafting prose here.
6. Validate the work
Confirm the site still builds: hugo completes without errors, hugo server renders the change,
and no new deprecation warnings were introduced. Report the outcome and any warnings.
1---2name: hugo-expert3description: Expert guidance for building and maintaining Hugo (gohugo.io) static sites — templating and layouts, theme creation and customization, content modeling, configuration and Hugo Modules, performance and the asset pipeline, deployment and CI, multilingual/i18n, SEO and feeds, and version upgrades. Fetches version-appropriate Hugo docs via Context7. Use inside or when starting a Hugo repo — building or customizing a theme, fixing or writing Go templates and partials, configuring hugo.toml or modules, optimizing builds, deploying, adding i18n or SEO, upgrading Hugo, or any "Hugo best practices" question. For writing blog posts in the author's voice, use hugo-write-post.4---56# Hugo Expert78Deep help with Hugo static sites. This skill carries durable Hugo best-practices and pins live9documentation lookups to the repo's actual Hugo version — Hugo ships frequently and APIs change, so10verify current syntax against the docs rather than from memory.1112## Preflight — live docs via find-docs1314Current Hugo syntax, template functions, and config keys are fetched with the `find-docs` skill15(Context7). Confirm it's available (it appears in your available skills); if it's missing, tell the16user and offer to install it — `npx skills find find-docs`. Without it, say so and proceed from17general knowledge, flagging that version-specific details may be stale.1819## 1. Detect the target version2021Run the detector at the repo root to pin doc lookups to the right version:2223```bash24"<skill-dir>/scripts/detect_hugo.py" .25```2627It reports the config file/format, the pinned Hugo version, Hugo Modules usage, an28extended-vs-standard hint, and configured themes. For a **brand-new repo** (`is_new_repo`), use the29**latest** Hugo release — look it up (`hugo version`, the GitHub releases page, or Context7); never30assume a hardcoded version.3132## 2. Fetch current docs when it matters3334Before asserting exact template-function signatures, config keys, or version-specific behavior, use35the `find-docs` skill to pull the current Hugo docs (library `Hugo` → `/gohugoio/hugo`). Query one36specific topic at a time, and pin the repo's version when it declares one. Rely on the references37below for durable practice; reach for live docs when the detail is version-sensitive.3839## 3. Route to the reference for the task4041Read only the file(s) the task needs:4243| Task | Reference |44|------|-----------|45| Go templates, partials, blocks, render hooks, lookup order | [references/templating.md](references/templating.md) |46| Creating/customizing a theme, overriding, publishing | [references/themes.md](references/themes.md) |47| Sections, page/leaf bundles, taxonomies, front matter, archetypes | [references/content-modeling.md](references/content-modeling.md) |48| `hugo.toml`/environments, Hugo Modules, mounts | [references/config-modules.md](references/config-modules.md) |49| Hugo Pipes, image processing, minify/fingerprint, caching | [references/performance.md](references/performance.md) |50| Netlify/Vercel/Pages, CI, `HUGO_VERSION`, `baseURL` | [references/deployment.md](references/deployment.md) |51| Version bumps, deprecations, extended vs standard | [references/upgrade-migration.md](references/upgrade-migration.md) |52| Multilingual sites, translations | [references/i18n.md](references/i18n.md) |53| Sitemap, RSS/output formats, meta/OpenGraph, structured data | [references/seo-feeds.md](references/seo-feeds.md) |5455## 4. Best-practice bar (holds across versions)5657- Prefer configuration over hardcoding; keep environment-specific values in `config/<env>/`.58- Build themes as **Hugo Modules** over copying files; override by shadowing layouts in the project.59- Compose layouts from **partials** and **render hooks**; don't duplicate markup across templates.60- Route CSS/JS/images through the **asset pipeline** (Hugo Pipes) — fingerprint and minify for production.61- **Pin `HUGO_VERSION`** in CI/deploy so local and production builds match.62- Verify with `hugo server` during work and a clean `hugo --minify` before shipping; treat build63 **warnings and deprecations** as work to resolve.6465## 5. Writing blog posts → delegate6667To write a blog post in the author's established voice, use the `hugo-write-post` skill rather than68drafting prose here.6970## 6. Validate the work7172Confirm the site still builds: `hugo` completes without errors, `hugo server` renders the change,73and no new deprecation warnings were introduced. Report the outcome and any warnings.
ricardodantas