# 智能体技能

> 教你的编码智能体编写、检查和自定义 htmlpress 站点。

Htmlpress 提供五个[智能体技能（Agent Skills）](https://agentskills.io/)，告诉 Claude Code、Cursor 和 Codex 等编码智能体 htmlpress 项目是如何运作的。安装之后，你的智能体就会了解页面约定、有哪些组件、允许哪些配置键、如何弹出布局、如何部署以及如何检查自己的工作。你无需在提示词中解释其中任何一项。

Htmlpress 让智能体的工作保持简单：编写语义化 HTML，只在 HTML 没有对应元素时才使用组件，并把样式交给主题。页面提供的选择越少，所有页面看起来就越像同一个站点。

| 技能                        | 你的智能体在以下情况使用它                                           |
| ------------------------- | ------------------------------------------------------- |
| `htmlpress-authoring`     | 编写或编辑页面：meta 标签、标题、组件、代码块、数学公式和引入文件                     |
| `htmlpress-configuration` | 编辑 `htmlpress.yaml`：分区、链接、补丁、include 和 exclude          |
| `htmlpress-customization` | 更改外观：令牌、弹出文件、布局和项目组件                                    |
| `htmlpress-landing`       | 设计落地页，以 htmlpress.dev 自己的落地页为参考                         |
| `htmlpress-knowledge`     | 为团队编写内部文档：调研、报告、登记表和决策记录                                |
| `htmlpress-deployment`    | 将构建结果发布到 Cloudflare、GitHub Pages、Vercel、Netlify 或任何托管平台 |

## 从网站安装

htmlpress.dev 在 [/.well-known/agent-skills/](/.well-known/agent-skills/index.json) 下发布其技能，因此 [`skills` CLI](https://github.com/vercel-labs/skills) 可以通过站点 URL 安装它们。在项目根目录运行：

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

它会询问要安装哪些技能以及为哪些智能体安装。要跳过这些提示，请以参数形式传入：

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

添加 `--global` 可为当前用户而非项目安装，添加 `--list` 可在不安装任何内容的情况下查看可用技能。之后运行 `npx skills update` 即可拉取更新的版本。

## 从软件包安装

这些技能也随 npm 和 PyPI 软件包一起发布。从软件包安装可让它们与 lockfile 中的 htmlpress 版本保持一致，而网站始终提供最新版本：

**npm**

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

**PyPI**

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

Python 软件包将它们安装到环境的 `share/htmlpress/skills`；使用 `cargo install` 时，请从网站安装。

## 使用技能

你无需亲自调用技能。智能体会读取每个技能的描述，并在任务匹配时加载它：请求新页面会加载 `htmlpress-authoring`，更改站点外观则会加载 `htmlpress-customization`。如果你的智能体支持按名称调用技能，你也可以直接调用，例如在 Claude Code 中使用 `/htmlpress-deployment`。

### 工作循环

1. 运行一次 `htmlpress --llms` 来了解各条命令。
2. 在项目文件夹中编写或编辑页面。
3. 运行 `htmlpress build <root> --json`，读取 `pages` 以及 stderr 上的任何错误。
4. 如需目视检查，运行 `htmlpress start <root>` 并在浏览器中打开页面。

### 值得交给智能体的规则

- 每个页面一个 `<title>` 和一个 `<h1>`；在导航顺序重要的地方添加 `<meta name="order">`。
- 不使用内联 `style`，不为外观添加类名：改为覆盖 `--htmlpress-*` 令牌。
- 只使用[文档中列出的组件](/zh/authoring/rich-elements/)；其余一律使用纯 HTML。
- 永远不要编辑 `.htmlpress/build`。

## 另请参阅

- [AI 智能体](/zh/customization/ai-agents/)：以同样的方式发布你自己项目的技能，与每次构建生成的 Markdown 副本和 `llms.txt` 放在一起。