# Agent Skills

> Teach your coding agent to write, check and customize an htmlpress site.

Htmlpress ships five [Agent Skills](https://agentskills.io/) that tell coding agents such as Claude Code, Cursor and Codex how an htmlpress project works. Once installed, your agent knows the page contract, which components exist, which config keys are allowed, how to escape the layout, how to deploy and how to check its work. You don't have to explain any of it in the prompt.

Htmlpress keeps an agent's job small: write semantic HTML, use a component only where HTML has none, and leave the styling to the theme. The fewer choices a page offers, the more pages look like one site.

| Skill                     | Your agent uses it when                                                               |
| ------------------------- | ------------------------------------------------------------------------------------- |
| `htmlpress-authoring`     | writing or editing pages: metas, headings, components, code blocks, math and includes |
| `htmlpress-configuration` | editing `htmlpress.yaml`: sections, links, patches, include and exclude               |
| `htmlpress-customization` | changing the look: tokens, escapes, layouts and project components                    |
| `htmlpress-landing`       | designing a landing page, with htmlpress.dev's own as the reference                   |
| `htmlpress-knowledge`     | writing internal docs for people: research, reports, registers and decisions          |
| `htmlpress-deployment`    | publishing the build to Cloudflare, GitHub Pages, Vercel, Netlify or any host         |

## Install from the website

htmlpress.dev publishes its skills under [/.well-known/agent-skills/](/.well-known/agent-skills/index.json), so the [`skills` CLI](https://github.com/vercel-labs/skills) can install them from the site URL. Run this at your project root:

```sh
npx skills add https://htmlpress.dev
```

It asks which skills and agents to install for. To skip the prompts, pass them as flags:

```sh
npx skills add https://htmlpress.dev --skill htmlpress-authoring --agent claude-code
```

Add `--global` to install for your user instead of the project, and `--list` to see what's available without installing anything. Run `npx skills update` later to pull newer versions.

## Install from the package

The skills also ship inside the npm and PyPI packages. Installing them from there keeps them matched to the htmlpress version in your lockfile, while the website always serves the latest release:

**npm**

```sh
npx skills add ./node_modules/gethtmlpress/skills
```

**PyPI**

```sh
npx skills add .venv/share/htmlpress/skills
```

A Python package installs them under the environment's `share/htmlpress/skills`; with `cargo install`, install them from the website.

## Use them

You don't need to invoke a skill yourself. Agents read each skill's description and load it when a task matches: asking for a new page loads `htmlpress-authoring`, a change to the site's look `htmlpress-customization`. If your agent supports invoking skills by name, you can also call one directly, as with `/htmlpress-deployment` in Claude Code.

### The loop

1. Run `htmlpress --llms` once to learn the commands.
2. Write or edit pages in the project folder.
3. Run `htmlpress build <root> --json` and read `pages` and any error on stderr.
4. For a visual check, run `htmlpress start <root>` and open the page in a browser.

### Rules worth giving an agent

- One `<title>` and one `<h1>` per page; a `<meta name="order">` where navigation order matters.
- No inline `style`, no classes for looks: override a `--htmlpress-*` token instead.
- Only the [documented components](/authoring/rich-elements/); anything else is plain HTML.
- Never edit `.htmlpress/build`.

## See also

- [AI Agents](/customization/ai-agents/): publish your own project's skills the same way, beside the Markdown copies and `llms.txt` every build writes.