Hugo Agent Skill

An agent skill that makes any AI coding agent an effective developer on any Hugo (static site generator) project — themes, templates, modules, content architecture, asset pipelines, deployment, and troubleshooting.

Works with any agent that supports the open Agent Skills format (Claude Code, Codex CLI, OpenCode, Antigravity, and others). The skill is deliberately agent-agnostic: guidance is phrased capability-first ("if a documentation-retrieval MCP is available…"), naming specific tools only as examples, and never assumes or promotes a particular agent.

Install

npx skills add HamStudy/gohugo-skill

Or copy this directory into your agent's skills location (e.g. .claude/skills/hugo/).

What's inside

• SKILL.md — mission, operating rules, workflow, and a map of the reference files. Agents load only the references relevant to the task.
• references/ — 14 focused reference files covering current-docs strategy, internal architecture, project structure, templates, markup, assets (SCSS/JS/Vite/webpack), images, modules and monorepos, content/data/i18n, security, SEO/outputs, deployment, troubleshooting, and real-world production patterns.
• agents/openai.yaml — optional display metadata for agents that read it; ignored by others.

Design principles

1. Verify over memory. Hugo evolves quickly. The skill teaches agents where current answers live (official docs, release notes, repo-analysis tools) and to distrust baked-in version claims — including its own.
2. Follow the project. Detect the existing conventions (config format, template style, asset pipeline) and work within them; defaults apply only to greenfield work.
3. Progressive disclosure. A small SKILL.md routes to topic references so agents don't load 2,000 lines of context for a one-line template fix.

Keeping it current

Every reference file carries a Last verified date. To refresh the skill as Hugo evolves:

1. Check Hugo releases since the oldest Last verified date.
2. Update the Version Landmarks section in references/current-docs.md (the canonical list of version-sensitive claims).
3. Grep the references for v0. and reconcile inline claims with the landmark list. Also re-check the small number of non-Hugo version claims (Vite backend integration, webpack manifest plugins, Go version requirements) against their own current docs.
4. Spot-check changed feature areas against https://gohugo.io/documentation/ and bump the Last verified dates you actually re-verified.

Issues and PRs that update version landmarks or add missing failure modes are welcome.

License

MIT — see LICENSE.