在 AI Agent 和 Claude Code 这类编程助手的使用群体中Jason Liu 征求“改进 AI 输出排版的 Skills 推荐”并不是一个孤立问题。它反映的是一个很实际的需求AI 能生成功能正确的代码但生成结果的排版、结构、可读性和前端观感往往不稳定。同样是生成一个页面有的模型输出层次清晰有的输出则标签混乱、样式内联且难以维护。Skills 机制的出现正好为这类问题提供了一种标准化的解决方案。这篇文章会围绕两条主线展开先讲清楚 Agent Skills 的运作方式和为什么“输出排版”值得做成一个 Skill再给出一组可以直接参考的 Skill 编写、安装、验证和排错方法。如果你正在使用 Claude Code、Codex、Cursor 或类似支持 Skills 的 Agent 工具并且经常需要 AI 输出更漂亮、更规范的页面或文档这篇文章会给出可落地的实践路径。1. 先理解 Agent Skills 和排版类 Skill 要解决什么问题1.1 Skills 本质上是一份可复用的操作说明书在 Claude Code、Codex 等 Agent 工具中Skills 并不是一个复杂的插件系统而更像是一份按固定格式组织的操作说明。一个 Skill 通常由一个目录构成目录里包含SKILL.md文件也可能附带参考文档、示例代码和测试数据。当 Agent 执行任务时会扫描当前项目或全局目录中的 Skills并根据任务内容判断是否需要调用某个 Skill。Skill 中的指令会被注入到模型上下文里指导模型按特定流程、特定规范完成任务。简单理解Skill 就是告诉 Agent“遇到这类任务时请按这份文档里的要求来做”。这种机制对输出排版的改进非常合适。普通 prompt 只能在单次对话里影响输出而 Skill 是持久化、可复用、可版本管理的。你对排版的所有要求从 HTML 结构到 Tailwind 类名规范从 Markdown 标题层级到代码块语言标注都可以固化成一个 Skill。以后每次让 AI 生成页面或文档它都会自动套用这套规范。1.2 为什么“AI 输出排版”是一个真实的工程痛点很多开发者刚接触 Claude Code 或 Codex 时最大的感受是功能确实强但生成界面的精细度不够稳定。常见的问题包括页面组件堆在一个文件里缺少组件拆分意识。样式全部写在style属性里维护成本高。使用 CSS 框架时不遵守命名约定类名随意组合。Markdown 文档标题层级跳跃从#直接跳到####。代码块不标注语言或者注释风格不统一。表格和列表嵌套混乱页面排版失衡。这些问题单看都不致命但叠加起来AI 生成的产品级页面就很容易变成“跑得通但看不下去”的状态。排版问题也不只是美观问题它还影响代码的可维护性、页面的响应式表现和后续迭代效率。把排版规范做成 Skill等于把团队对“什么才算合格输出”的标准固化下来让 AI 每次生成都按统一标准执行。1.3 排版 Skills 与传统前端模板的区别有人会觉得排版问题用现成 UI 组件库或模板就行为什么还要 Skill这是两种不同层面的解决方式。传统模板是固定输出。你给 AI 一个 Vue 组件模板它生成的结构是相对固定的但遇到复杂场景时AI 可能会强行往模板里套内容反而产生奇怪结构。排版 Skill 是行为约束。它不是规定“你必须输出某个组件”而是规定“你生成页面时结构、命名、样式组织、响应式处理必须遵守这些规则”。模型仍然有生成自由但自由被约束在合理范围内。Skill 可以叠加使用例如你同时配置了“前端布局规范 Skill”和“Tailwind CSS 使用 Skill”Agent 会同时参考两者很多情况下比单一模板更灵活。2. 拆解“AI 输出排版”到底要约束哪些维度2.1 内容结构先定骨架再填血肉排版优化的第一层是内容结构。AI 生成页面时经常会出现的问题是没有先规划区块直接从上到下输出一堆div。结构层面的约束应该包括页面必须有明确的语义化标签优先使用header、main、section、footer而不是满屏div。每个区块应有明确的注释说明该区块的用途。标题层级必须连续不能从h2直接跳到h5。区块内内容不超过一定规模时应拆分子组件或子模块。如果针对的是 Markdown 文档则约束为标题层级、列表嵌套深度、表格列数、图片 alt 文本等。2.2 样式组织内联样式是维护性最大的敌人AI 生成的页面另一个典型问题是样式组织混乱。常见的有所有样式写成内联style、CSS 类名随意缩写、Tailwind 类名顺序不稳定、颜色用魔法值而不用主题变量。样式类 Skill 的核心规则应该包含禁止无理由使用内联样式。抽离公共样式变量颜色、间距、圆角、字体大小统一使用变量。CSS 类名遵循 BEM 或团队约定不使用无意义缩写。如果使用 Tailwind类名按布局、外观、间距、交互顺序排列。这类约束写成 Skill 后AI 生成的前端代码在结构上会干净很多。尤其是多人协作场景下组件代码是否规范直接影响 review 效率。2.3 响应式与交互细节移动端优先不是口号排版不只是静态观感还包括不同屏幕下的表现。AI 生成页面时经常忽略响应式只按桌面宽度设计。排版 Skill 中应明确要求默认采用移动端优先的布局思路使用grid或flex-wrap实现自然降级。关键断点需要适配中等屏幕和小屏幕。弹窗、表单、表格在窄屏下不能强制横向滚动。交互状态必须包含 hover、focus、disabled 等基础状态。2.4 可读性与空白控制信息密度要合理很多 AI 生成的页面在真实设备上显得拥挤原因是缺少合理的间距系统。排版 Skill 可以规定间距默认值例如统一使用 4px 或 8px 的倍数段落行高不低于 1.6卡片之间的间距保持一致。这样的规则写成数字模型更容易执行。3. 推荐哪几类排版相关 Skills以及如何判断它们好不好用3.1 推荐方向和典型场景在 Jason Liu 的原始提问场景里推荐 Skills 不能只给名字还要说明适用场景和判断标准。下表整理了几类值得纳入候选范围的排版相关 Skills。Skill 类型解决的核心问题适用工具推荐程度前端布局规范类强制语义化标签、合理嵌套、组件拆分Claude Code、Codex、Cursor高CSS 框架规范类统一 Tailwind、Bootstrap 类名和变量用法Claude Code、Codex高Markdown 排版规范类统一文档标题层级、表格规范、代码块标注所有 Agent 工具高数据可视化排版类规范图表配色、标签、图例位置AI 数据分析场景中测试用例格式类统一 Given/When/Then 式输出间接提升文档可读性后端测试生成场景中结构图生成类指导 Agent 输出 Text Diagram、ASCII Flow 或 PlantUML架构设计场景中如果你正在 Cursor 中做前端开发最值得优先配置的是“前端布局规范 CSS 框架规范”的组合。如果主要使用 Claude Code 撰写技术文档Markdown 排版规范的效果最直接。3.2 判断 Skill 质量的六个维度网上可以找到很多开源 Skills例如 GitHub 上有人整理了各类claude skills、codex skills。但命名相似不代表实现可靠。建议按这六个标准筛选指令明确性SKILL.md里是否用“必须”“禁止”定义规则还是含糊的“尽量”。有示例代码好的 Skill 必须附带正反示例模型才知道标准长什么样。边界清晰Skill 是否说明自己不适用于哪些场景避免被错误触发。长度适中过长会稀释模型注意力过短又缺少约束力一般 100 到 300 行为宜。可验证性Skill 内部是否提供输出清单或自检步骤。维护活跃度开源 Skills 的更新时间、issue 回复情况可以作为参考但不能当成唯一指标。注意不要因为某个 Skills 仓库 star 数高就直接套用。先在小项目里验证效果确认规则与需求匹配后再放进团队公共目录否则它的“规范”可能和你的现有代码风格冲突。3.3 如果找不到合适的开源 Skill自己写是更可靠的选择目前开源社区里专门针对“AI 输出排版”的成熟 Skills 数量仍在快速增长但质量参差不齐。与其花大量时间检索和适配完全可以花半小时自己编写一个。下一节会给出一个可直接运行的排版 Skill 示例。4. 自己动手编写一个输出排版 Skill最小可运行示例4.1 先确定 Skill 的目录结构一个最简单的 Skill 可以只包含一个SKILL.md文件。推荐结构如下frontend-layout-skill/ ├── SKILL.md ├── examples/ │ ├── good-example.html │ └── bad-example.html └── references/ └── naming-conventions.mdSKILL.md是入口examples里放正反示例references放补充规范。模型在上下文空间不足时会优先读取SKILL.md按需读取 references所以主文档必须精简。4.2 编写 SKILL.md 核心内容下面是一个针对前端页面生成的排版 Skill 示例。它解决的问题是让 Agent 生成 HTML 页面时结构、样式命名、响应式和可维护性都符合基础工程规范。--- name: frontend-layout-skill description: 当需要生成或重构 HTML 页面、前端组件、文档结构时使用。重点是规范页面结构、样式组织、响应式布局和代码可读性。 --- # 前端布局规范 Skill ## 使用场景 - 根据需求生成新的 HTML 页面或组件。 - 对 AI 生成的页面进行重构和润色。 - 为 Markdown 文档设计目录结构和层级。 ## 核心规则 ### 1. 页面结构 - 必须优先使用语义化标签header、nav、main、section、article、aside、footer。 - 禁止连续嵌套三层以上无意义的 div。 - 每个 section 必须有明确的注释说明该区域用途。 - 标题层级必须连续禁止从 h2 跳转到 h5。 ### 2. 样式组织 - 禁止使用内联 style 编写业务样式除非是动态计算值。 - 颜色、间距、字号必须使用 CSS 变量或主题 token。 - 类名遵循 BEM 风格block__element--modifier。 - 每个类名必须能表达元素用途禁止使用 a1、b2 等无意义命名。 ### 3. 响应式 - 默认使用移动端优先布局。 - 使用 CSS Grid 或 Flexbox 实现弹性布局。 - 表格在窄屏下必须允许水平滚动或进行卡片化处理。 - 弹窗和表单控件必须适配键盘操作。 ### 4. 可读性 - 段落行高不小于 1.6。 - 组件间距使用 4px 的倍数。 - 单个文件超过 300 行时必须拆分组件。 - 提交前必须删除注释掉的死代码。 ## 输出清单 生成完成后按以下清单自检 - [ ] 是否使用了语义化标签 - [ ] 是否消除了无关内联样式 - [ ] 是否有无意义类名 - [ ] 窄屏下是否出现横向滚动 - [ ] 标题层级是否连续 ## 示例参考 正例和反例见 examples 目录。这个 Skill 的写法有几个值得注意的地方description字段非常关键它决定模型什么时候会触发这个 Skill。描述里既要说明适用场景也要尽量覆盖任务标签例如“生成页面”“重构组件”“文档结构”。规则用“必须”“禁止”表述比“建议”“尽量”更容易被模型执行。输出清单很有价值它让模型在生成后自动执行一次自检。这等于把人工 review 的一部分工作交给模型完成。4.3 编写正反示例文件examples/good-example.html和examples/bad-example.html不需要太长但对比要清晰。下面是一个极简对比。good-example.htmlsection classproduct-card aria-label产品信息 h2 classproduct-card__title无线降噪耳机/h2 p classproduct-card__desc30 小时续航支持主动降噪。/p button classproduct-card__button product-card__button--primary加入购物车/button /sectionbad-example.htmldiv stylepadding: 10px; div div h5无线降噪耳机/h5 span30 小时续航支持主动降噪。/span a stylecolor: blue;加入购物车/a /div /div /div正反示例的作用是拉近“规则”和“模型理解”之间的距离。模型看到正反例后能更加准确地把握预期标准。4.4 安装并加载到 Agent 工具中不同工具加载 Skill 的方式略有区别。这里给出通用思路项目级把 Skill 目录放在项目的.claude/skills/或.codex/skills/下。只有当前项目能使用。全局级放在用户主目录下的全局 Skills 目录中例如~/.claude/skills/。所有项目可用。通过CLAUDE.md或AGENTS.md引用目录。部分工具允许在项目配置文件中指定自定义 Skill 路径。以 Claude Code 常见做法为例可以在项目根目录的CLAUDE.md中加入## Skills - 前端布局规范使用 .claude/skills/frontend-layout-skill - Markdown 排版规范使用 .claude/skills/markdown-layout-skill加载完成后可以在对话中直接提问使用 frontend-layout-skill 生成一个对应移动端和桌面端的商品详情页。如果工具正确触发 Skill输出会明显表现出结构化和规范化特征。注意Skill 目录名称、name字段和description中的场景词要保持一致。如果它们互相矛盾模型可能无法正确关联任务和 Skill。5. 验证 Skill 是否生效以及输出质量如何评估5.1 验证 Skill 是否被模型调用你无法直接看到模型内部是否读取了SKILL.md但可以通过两种方式间接判断。第一种是观察输出风格如果生成结果里的类名、结构、注释风格有显著改变说明 Skill 生效。第二种是在对话中主动询问部分 Agent 工具允许打印当前加载的上下文信息例如 Claude Code 的/context命令。如果怀疑 Skill 没有生效优先检查以下项目文件路径是否在正确目录下。SKILL.md文件名是否准确大小写是否一致。项目级配置和全局配置是否冲突。工具版本是否支持 Skills 机制。例如旧版 Claude Code 可能只能识别协议但不完整支持。5.2 用“最小验收清单”评估输出质量Skill 是否起作用不要凭感觉可以用验收清单打分。下面是一个基础版排版验收清单验收项判定标准结果语义化结构页面主体不使用无意义 div 包裹通过 / 不通过标题层级不跳级顺序连续通过 / 不通过样式组织无内联样式或只有必要动态样式通过 / 不通过类名可读性类名能表达用途符合 BEM通过 / 不通过响应式表现窄屏无横向滚动通过 / 不通过注释规范区块注释清晰无死代码通过 / 不通过建议在一开始就用这个清单做基准测试。改造前生成一次页面启用 Skill 后生成同需求页面对比两次得分。这个对比结果也能验证 Skill 编写的有效性。5.3 实测效果不理想时怎么办如果验证发现 Skill 没有产生明显改变最可能的原因是规则与模型的执行方式不匹配。常见有三种规则太抽象。像“输出要好看”这种规则模型无法量化应改成“间距使用 4px 倍数”“行高不小于 1.6”。正反例太少。模型需要更多示例才能稳定模仿。description触发词不足。你问“生成一个商品卡片”但描述里只写了“生成页面”模型就不会触发。修正后重新运行一次通常都能看到改进。6. 常见问题与排查路径6.1 Skill 被触发但生成结果不稳定现象同样一次任务有时候输出很规范有时候又退回默认风格。可能原因模型上下文过长Skill 内容被截断或权重降低。同一个任务命中了多个 Skill规则冲突。检查方式查看上下文长度和命中的 Skill 列表把任务拆小在单次生成中只依赖一个核心 Skill。解决建议精简SKILL.md内容让核心规则集中在前部将不同领域的规则拆成独立 Skill。6.2 Skill 没有生效输出和之前完全一样现象配置完成后生成的代码风格没有变化。可能原因Skill 文件路径放错。工具版本不支持新目录结构。name或路径与配置不一致。项目级配置覆盖了全局配置。检查方式用文件管理器确认路径使用工具提供的上下文查看命令查看启动日志中是否包含 Skills 加载记录。6.3 多个 Skill 规则互相冲突现象同时启用“响应式布局 Skill”和“组件库 Hero 区 Skill”后生成的代码出现自相矛盾的结构。可能原因两个 Skill 对同一元素给出了不同规则模型无法判断优先级。检查方式打开两个SKILL.md搜索重叠的关键词和冲突指令。解决建议在SKILL.md中加入“如果与其他 Skill 冲突以本 Skill 为准”的说明或者把相关规则合并到同一个 Skill。6.4 Skill 导致上下文占用过大现象配置大量 Skill 后模型可用上下文减少答案变短或遗忘早前指令。可能原因每个 Skill 的SKILL.md过长且被同时加载。检查方式统计所有启用的 Skill 的字符总量对照工具上下文长度。解决建议主文档只保留高频规则详细示例放入 references 目录按需读取。生产环境下建议每个项目只启用 3 至 5 个核心 Skill。6.5 表格常见问题速查问题现象可能原因检查方式解决方案完全不生效路径、文件名、工具版本不匹配检查目录结构和版本日志修正路径升级工具版本时好时坏上下文过长、多 Skill 冲突查看上下文大小和命中列表精简 Skill缩小任务粒度风格不一致缺少正反例检查 examples 是否完整补充正反示例触发不准确description 描述过窄阅读 description 字段增加场景关键词规则被忽略规则太抽象查看 SKILL.md 表述改成“必须”“禁止”量化标准7. 排版 Skills 最佳实践与扩展方向7.1 发布前的排版 Skills 检查清单无论从开源社区下载还是自己编写投入生产之前建议按这个清单检查[ ]SKILL.md具备name和description字段描述覆盖典型触发场景。[ ] 规则使用明确指令词而不是模糊建议。[ ] 包含至少一个正例和一个反例。[ ] 包含输出后自检清单。[ ] Skill 目录不放在会被编译器打包或过滤的目录中。[ ] 版本管理使用 Git变更记录可回溯。[ ] 多 Skill 之间无重复或冲突规则。[ ] 在空项目和真实项目中各验证过一次。这套清单也适合团队引入 Skills 时作为 review 依据。它能够防止“看起来加了 Skill实际上没有用”的情况。7.2 结合其他编程场景扩展 Skill 库排版类 Skill 的价值并不局限于页面生成。它可以延伸到多个相邻场景测试用例排版在生成单元测试或接口测试时规定 Given/When/Then 的输出格式。输出结果更适合阅读和 review。接口文档生成规定错误码表格、请求参数表格、响应示例的排版方式。数据可视化规范配色数量、标签位置、中文注释的样式。项目结构说明规定 README 中目录树、环境变量、脚本命令的展示方式。这些 Skill 都不需要太复杂核心思路是一致的用结构化的规则约束 Agent 的输出形式。7.3 让 Skill 可迭代而不是一次写完Skill 是一份活文档。首次编写往往只能覆盖 70% 的场景后续应该在使用中持续补充。推荐的迭代方式是每两周回顾一次模型生成的失败案例。将失败案例中暴露的问题转成新的规则条目。把典型的反例沉淀到 examples 目录。同步更新输出清单让模型自检覆盖新问题。这种迭代方式最大的好处是团队对“好输出”的定义会越来越一致而不会停留在个人经验层面。7.4 避免把 Skill 写成“巨型 prompt”编写排版 Skill 时有一个常见误区试图把所有规范一次性写入SKILL.md。一旦主文档超过 500 行模型在上下文受限时容易丢失后部规则反而降低稳定性。推荐的做法是主文档控制在 100 到 300 行详细规范分散到 references 中按需加载。这也符合 Agent Skills 设计的基本思想入口简洁内容按需展开。在实际项目中建议从最小用例开始先用 20 条规则跑通一个页面生成任务确认效果好之后再逐步增加规则。这样既能保证模型输出的稳定性也便于定位是哪条规则在起作用。