One command, four roles

HERON skills

A skill is a short instruction an AI agent loads when a task needs it. HERON has four skills, one for each role in building a site. Each tells the agent how a HERON site works, what it may change and what it must leave alone.

They work in Claude Code, Codex and other agents that read skills from skills.sh.

Install

Run the command in your site folder or repository.

All four skills

The usual choice: the agent picks the skill that fits the task. You give an ordinary task in your own words; the right rules load on their own.

npx skills add FMSTM/HERON

Where they go: Into the skills folder of your agent, next to the site.
Update: Run the same command again when HERON releases a new version.
You need: Node.js, which brings the npx command. Check with node --version.
Check: Ask the agent «which HERON skills do you have?»: it should name four.

Only the skills you need

For an agent that does one job, for example only content. Fewer skills means the agent cannot drift into work you did not give it.

npx skills add FMSTM/HERON --skill heron-content

Tip: List several with a comma: heron-content,heron-builder.
For a client or an editor: Give them only heron-content: they can change texts and cannot break the theme.

Without skills

Agents that do not read skills get the same rules from HERON itself. The exported folder holds the guides, the roles and the specifications of your HERON version.

heron docs --export .heron-docs && ls .heron-docs

Then: Tell the agent: «Read .heron-docs/AGENTS.md and work as the content role».
More: HERON for AI agents

What each skill may change

Skill	Writes to	Never touches
heron-content	`content/`, `media/`, `data/`	`theme/`, `site.yaml`, `scripts/`, `.github/`
heron-designer	`theme/`	`content/`, `site.yaml`, `scripts/`, `.github/`
heron-architect	the structure plan, `site.yaml`	page texts, `theme/` templates
heron-builder	`dist/`, the image, the report, `.github/workflows/`	HERON itself; other roles' files only within their limits

The four skills

heron-content

Writes and translates pages and fills the search settings at the top of each file. The skill you will use every week.

Use when: New pages, translations, texts and search settings.
Hands over: Files in content/, images in media/, a list of missing facts.
May write: content/, media/, data/.
May not: theme/, site.yaml structure, scripts, .github/.
Rules: Content role

heron-designer

Builds a theme that draws every page type and still looks right when part of the content is missing. Usually needed once per site, or when the look changes.

Use when: A new look, a mockup to turn into a theme, a new block.
Hands over: The theme/ folder: templates, modules, interface texts, styles.
May write: theme/ only.
Rule: No texts of the site in templates; interface words go to the theme's language files.
Rules: Designer role

heron-architect

Plans the site: pages and addresses, page types and their blocks, languages, the move from an old site. It works before anyone writes a page.

Use when: You start a new site or move an old one.
Hands over: A structure plan, a draft site.yaml, a table of old and new addresses.
Asks you: Questions with options and a recommendation, when a decision is yours.
Rules: Architect role

heron-builder

Makes the strict build pass, packs the image, runs the test and publishes. Can lead the other three, each within its own limits. Give it the whole job and get a report back.

Use when: "Build the site", "publish it", "why does the build fail".
Hands over: dist/ or an image, and a report.
Never: Puts tokens, Dockerfiles or server settings into the site folder.
Rules: Builder role

Rules every skill keeps

Facts are never invented

Phones, prices, addresses and names come from you. When they are missing, the field stays empty and the agent lists it.

One file for settings

Languages, domain, menu and counters live in site.yaml and nowhere else.

A warning is work

The strict build turns warnings into errors; the agent fixes them and does not hide them.

HERON is not changed from a site

If something is missing, the agent writes it down as a task and uses the simplest honest option on the site.

Questions

Why can't the content skill change the theme?

So that a page edit never breaks the look of the site. Text and design are separate jobs; you decide when the design changes.

Do the skills work offline?

The skills are files in your project. Without the internet, export the docs with heron docs --export, and the agent reads them from the folder.

Can I change a skill for my team?

Yes, they are plain text files. Keep the limits on folders: they are what keeps a content edit from touching the design.