企业官网建设流程全解析

Jason Liu 在问“怎么用 Skills 改善 AI 输出排版”，这问题值得每个做 AI 应用的人思考

最近 AI 圈子里有个讨论挺有代表性：Jason Liu（就是做 LLM 应用性能优化、写过不少关于推理优化和结构化输出文章的那位）公开征求大家推荐“改进 AI 输出排版的 Skills”。乍一看，这问题好像不太“硬核”——排版算啥技术难题？但真做过 AI 应用的人都知道，模型输出这东西，内容对了不代表能直接用。一段逻辑完整的 Markdown 文本，可能在换行、表格、代码块、标题层级上“形散神也散”，落到实际生产环境就是灾难。Jason Liu 关注这个点，本质上是在关心“模型输出如何从能用变成好用”。

这次讨论背后，是当下 AI 工具链里一个非常值得关注的趋势：Agent Skills。无论是 Anthropic 的 Claude Skills、OpenAI Codex 的 skills 机制，还是社区里的 opencode skills、baoyu skills，大家都在把“技能包”当成模型能力的外挂。Skills 到底是什么？简单说，它是一组封装好的指令、示例代码和规则，让模型在特定任务里调用，从而稳定输出。排版 Skills 就是其中一类：把“怎么组织 Markdown”“表格怎么写”“代码块怎么排版”“标题怎么分级”这些规则固化下来，让模型每次输出都按标准执行。

这篇文章会围绕“AI 输出排版”这个具体痛点，展开聊聊：排版 Skills 能解决什么问题、怎么设计一份可用的排版 Skills、怎么接入 Claude Code / Codex / opencode 这类工具、怎么验证效果，以及在实际批量任务和 API 服务中怎么落地。如果你正在做 AI 应用开发、写 AI 提示词工程，或者只是被模型输出格式搞得头疼，这篇可以直接收藏。

1. 核心能力速览：排版 Skills 能带来什么

先把 Jason Liu 这个讨论里最核心的“排版 Skills”到底是什么，用一张表讲清楚。这里不是某个具体开源项目的下载地址，而是一类技术方案的能力清单。根据目前社区里的公开讨论和主流 AI 编程工具（Claude Code、Codex、opencode）的 Skills 机制，排版 Skills 的核心能力大致如下：

从这张表能看出，排版 Skills 并不是一个“锦上添花”的装饰性能力。它真正的价值在于：把模型输出的“玄学”变成“确定性”。模型知道内容怎么写，但不知道你项目的排版规范是什么。Skills 就是那个“把你的规范告诉模型”的桥。

值得注意的一点是，排版 Skills 本质上属于 Agent Skills 的一个子类。随着 Claude Code Skills 官方文档的完善、Codex 对自定义 Skills 的支持，这类“技能包”正在成为 AI 应用开发的基础设施。与其说 Jason Liu 在征集一个排版脚本，不如说他在探索“模型输出质量控制”的工程化路径。

2. 适用场景与使用边界：排版 Skills 不是银弹

排版 Skills 适合解决什么问题？我认为至少有三类场景是它的主场。

第一类是文档自动生成与批量整理。比如你让 AI 批量生成产品说明、周报、论文初稿、测试用例，如果没有排版约束，每篇输出的标题层级可能都不一样，有的用##有的用###，有的列表嵌套错乱，有的表格宽度爆炸。这时候排版 Skills 能把“生成 100 篇文章”变成“生成 100 篇格式完全一致的 文章”。

第二类是代码与文档混排输出。很多 AI 编程工具在生成代码时，会把解释文字、代码块、输出结果混在一起，代码块没有语言标注，或者注释格式不统一。排版 Skills 可以规定“代码块必须标注语言、说明文字使用列表、输出结果使用 blockquote”。

第三类是结构化数据展示。模型输出 JSON、CSV、XML 时，缩进、换行、字段排序都可能不一致。排版 Skills 可以强制要求输出经过校验的 JSON Schema，并统一缩进风格。

但也要说清楚边界。排版 Skills 解决的是“格式规范”问题，不是“内容质量”问题。模型如果本身逻辑混乱、事实错误，排版再漂亮也没用。它也不是一个能处理所有格式的万能工具，PDF 转 Word、论文双栏排版这类涉及复杂版式的任务，需要专门的解析和渲染工具链，排版 Skills 更适合处理文本标记语言（Markdown、reStructuredText、LaTeX）和结构化数据。

合规和使用边界也必须强调：如果排版 Skills 处理的是用户上传的文档、代码、论文，要注意数据隐私，不要将敏感内容发送到不受信任的外部模型服务。如果涉及人脸、声音、版权素材，需要有明确授权。Skill 本身如果是第三方下载的，要检查是否包含危险的系统操作指令。发布或商用前要做效果复核。

3. 环境准备：搭建排版 Skills 的运行环境

排版 Skills 的形态通常是“指令文件 + 脚本”，所以环境准备不复杂。但为了让 Skill 能真正被模型调用，需要准备好三样东西：支持 Skills 的模型工具、一个用于验证的本地目录、以及基础的 Python/Node 运行环境（如果 Skill 包含脚本）。

3.1 工具链选择

从社区讨论和当前主流工具看，支持 Skills 的工具有这么几类：

• Claude Code：Anthropic 官方 CLI 工具，支持自定义 Skills，可以参考 Claude Code Skills 官方文档部署。
• Codex CLI：OpenAI 的编程 Agent，社区已经有不少关于“codex skills 如何使用”的教程。
• opencode：开源终端 AI 助手，支持自定义 agent skills。
• Cursor / Windsurf 等 IDE：支持自定义指令和规则文件。

如果只是想先验证排版效果，不一定要装完整工具链。可以把排版 Skills 写成一条综合提示词，在任意支持长上下文的模型里测试。但正式落地，建议用支持 Skills 机制的工具，因为 Skills 可以在任务中自动触发，而不是靠用户每次复制提示词。

3.2 本地环境清单

# 确认系统环境 node --version # Node.js 16+，部分 Skills 工具链需要 python --version # Python 3.9+，跑脚本用 git --version # 用于拉取 Skills 仓库

最好不要把版本写死，以实际项目为准。磁盘空间方面，一个排版 Skills 本身不到 1MB，但如果要配合本地模型，至少要预留模型文件的空间。端口方面，Skills 本身不占端口，但如果要把 Skill 封装成 API 服务，建议预留一个端口，例如 8760。

4. 排版 Skills 的设计与实现：从 SKILL.md 到可执行脚本

先明确一个概念：一个完整的排版 Skills 通常包含两个部分：一是给模型看的“行为规范”，二是可执行的“格式处理脚本”。行为规范告诉模型“遇到什么情况应该怎么排版”，脚本则用于批量清理已有文本。

4.1 设计一份排版 SKILL.md

以“中文 Markdown 排版”为例，SKILL.md 可以这样设计：

# Skill: markdown-format ## 功能 将模型输出或用户输入文本，统一格式化为符合规范的 Markdown 文档。 ## 规范要求 ### 标题层级 - 一级标题只能有一个，放在文档最上方。 - 二级标题使用 `##`，三级标题使用 `###`，禁止跳级。 - 标题与正文之间必须空一行。 ### 正文排版 - 中文与英文、数字之间加一个空格。 - 列表项使用 `-`，嵌套列表缩进两个空格。 - 强调使用 `**`，不使用 `__`。 - 引文使用 `>`，代码块使用带有语言标注的围栏代码块。 ### 表格 - 表头与数据行使用 `|` 分隔。 - 表格前后必须空一行。 - 对齐不使用冒号，除非有特殊要求。 - 列数不超过 6 列。 ### 代码块 - 代码块必须标注语言，例如 ` ```python `。 - 函数、类名使用反引号包裹。 - 代码块内部禁止追加说明性文字。 ## 输出要求 - 输出格式必须为 UTF-8 编码的 Markdown。 - 文档末尾保留一个换行符。 - 不要输出任何解释性文字，只输出格式化后的正文。

这份 SKILL.md 的核心是把“排版规范”显式化。模型在执行任务时读到这份文件，就会按规范调整输出格式。Skill 的加载方式在不同的工具里略有不同，但大体都是把 SKILL.md 放到指定目录，然后在任务中触发。

4.2 写一个可执行的格式化脚本

SKILL.md 是给模型看的规则，但它不保证 100% 执行。对于已经生成的大量文本，更可靠的方案是配套一个 Python 脚本做“物理校验和修正”。下面给出一个最小可用的 Markdown 自动排版脚本。

#!/usr/bin/env python3 # -*- coding: utf-8 -*- """ markdown_formatter.py 简单 Markdown 排版脚本：修复中英文空格、代码块语言标注、标题层级。 实际效果需按项目需求扩展，这里给出最小示例。 """ import re import sys from pathlib import Path def add_chinese_english_space(text: str) -> str: """中文与英文/数字之间加空格""" text = re.sub(r'([\u4e00-\u9fff])([A-Za-z0-9])', r'\1 \2', text) text = re.sub(r'([A-Za-z0-9])([\u4e00-\u9fff])', r'\1 \2', text) return text def ensure_code_block_language(text: str) -> str: """为没有标注语言的代码块补上 text 标注""" lines = text.split('\n') in_code = False for i, line in enumerate(lines): if line.strip().startswith('```'): if not in_code: in_code = True # 行内内容只剩 ```，没有语言标注 if line.strip() == '```': lines[i] = line.replace('```', '```text') else: in_code = False return '\n'.join(lines) def normalize_headings(text: str) -> str: """确保标题与正文之间有空行""" text = re.sub(r'(#[^\n]+)\n(?=\S)', r'\1\n\n', text) text = re.sub(r'\n{3,}', '\n\n', text) return text def format_markdown(text: str) -> str: text = add_chinese_english_space(text) text = ensure_code_block_language(text) text = normalize_headings(text) return text.strip() + '\n' def main(): if len(sys.argv) < 2: print("用法: python markdown_formatter.py <输入文件.md> [输出文件.md]") sys.exit(1) input_path = Path(sys.argv[1]) output_path = Path(sys.argv[2]) if len(sys.argv) > 2 else input_path text = input_path.read_text(encoding='utf-8') formatted = format_markdown(text) output_path.write_text(formatted, encoding='utf-8') print(f"排版完成: {output_path}") if __name__ == '__main__': main()

这个脚本做了什么？第一，在中文与英文/数字之间加空格，这是中文排版的硬性要求；第二，给没有标注语言的代码块补上text标注，避免高亮混乱；第三，规范标题与正文之间的空行；第四，去重多余空行。它相对简单，但能帮模型把“规范sense”变成“可见动作”。

4.3 让模型“学会”这个 Skill 的三步走

第一步，把 SKILL.md 放到工具的 Skills 目录，比如 Claude Code 的.claude/skills目录。第二步，在任务里明确要求“调用 markdown-format 技能处理输出”。第三步，用格式化脚本做兜底校验，发现模型输出不符合规范时，直接脚本修复。

这个“规范 + 脚本兜底”的结构，就是 Jason Liu 讨论里最值得借鉴的地方。光靠提示词约束，模型偶尔会“忘记”规范；光靠脚本，无法处理复杂语义结构。两者结合，才是可靠的排版方案。

5. 功能测试与效果验证：怎么确认排版 Skills 真的有效

写完一套排版 Skills，不能只看一两次输出就说“有效”。这里给出一套可复用的验证流程，用工程测试的思路检验排版能力。

5.1 准备测试素材

准备一份包含各种常见格式问题的 Markdown 文档，至少包含：

• 标题层级混乱（从##直接跳到####）。
• 中文与英文之间没有空格。
• 代码块没有语言标注。
• 表格前后没有空行。
• 列表嵌套错误。

素材可以直接手写，也可以让 AI 故意生成一份“乱排”文档，方便对照。

5.2 测试维度与预期结果

5.3 判断是否成功

对每个测试用例，用以下标准判断：

• 规范性：输出是否符合 SKILL.md 定义的全部规则。
• 一致性：同一输入重复跑 5 次，结果是否基本一致。
• 保真性：排版是否改变了原文档的语义，是否丢失了内容。
• 稳定性：长文本（5000 字以上）是否还能稳定执行规范。

如果重复测试时模型输出不稳定，优先检查 SKILL.md 里的规则是否足够明确，是否存在“一部分规则可执行、一部分规则是废话”的情况。常见的失败原因包括规则互相冲突、规则太笼统、模型上下文过长导致后半段遗忘规范。解决方案是把最关键的规则前置，或者把 SKILL.md 放到系统提示词/最高优先级位置。

5.4 批量验证与回归

当排版 Skills 要投入使用前，建议做一个批量验证：

# 假设有一个 ./test_cases 目录存放测试文件 for f in ./test_cases/*.md; do python markdown_formatter.py "$f" "./outputs/$(basename "$f")" done

跑完批量脚本后，抽查 20% 的输出文件，确认没有引入格式错误。这一步在批量生成文档时尤其重要，因为单个文件格式对了不代表 100 个文件都对了。

6. 排版 Skills 的接口 API 与批量任务：接入业务系统的思路

Skill 不只是“让模型在对话框里输出规范的 Markdown”。如果把 Skill 中的格式化能力封装成 API，就能把它接入到业务流程里，实现批量文档处理、自动发布前检查等操作。这里给一个通用的接口设计思路。

6.1 本地 API 封装示例

可以用 FastAPI 把格式化脚本封装成服务：

from fastapi import FastAPI, HTTPException from pydantic import BaseModel import uvicorn # 导入上面写的 markdown_formatter 函数 from markdown_formatter import format_markdown app = FastAPI(title="Markdown Format Service") class FormatRequest(BaseModel): content: str style: str = "chinese-markdown" # 可选扩展风格 class FormatResponse(BaseModel): content: str @app.post("/api/format", response_model=FormatResponse) async def format_content(req: FormatRequest): if not req.content.strip(): raise HTTPException(status_code=400, detail="内容不能为空") formatted = format_markdown(req.content) return FormatResponse(content=formatted) if __name__ == '__main__': uvicorn.run(app, host="127.0.0.1", port=8760)

启动服务：

pip install fastapi uvicorn python api_server.py

然后可以用 curl 测试：

curl -X POST http://127.0.0.1:8760/api/format \ -H "Content-Type: application/json" \ -d '{"content": "使用AI工具完成排版任务，支持PDF导出。"}'

预期返回{"content": "使用 AI 工具完成排版任务，支持 PDF 导出。"}。这个接口可以部署在内网，接入内容管理系统或文档流水线。

6.2 批量任务的工程化建议

批量处理大量文档时，建议在接口外加一层任务队列，避免同步请求超时。通用的结构是：

{ "task_id": "task-001", "status": "pending", "input_dir": "./inputs", "output_dir": "./outputs", "files": [ {"name": "a.md", "status": "waiting"}, {"name": "b.md", "status": "waiting"} ] }

处理流程大致是：扫描输入目录 -> 依次调用格式化接口 -> 写回输出目录 -> 记录处理日志。每一步都要写日志，失败的任务要有重试机制。如果某个文件在重复失败，把它单独隔离，不要阻塞整个队列。

6.3 Skills 与模型接口的分工

有一点要理清：格式化接口负责“后处理”，模型仍然负责“内容生成”。最佳实践是让模型先生成内容，再调用格式化服务做检查修正。不要指望模型直接生成完美格式，也不要指望格式化脚本能生成内容。两者职责分开，系统才稳定。

7. 资源占用与性能观察：排版 Skills 重不重

排版 Skills 的“资源占用”要分两层看：一层是模型调用层的资源，另一层是脚本执行层的资源。

模型调用层：如果用的是 Claude Code 或 Codex 这类云端模型，本地不需要 GPU，Skill 上消耗的 token 主要是读取 SKILL.md 的成本。一份 SKILL.md 大概 500 到 1500 个 token，对长任务来说占比不高。如果用的是本地模型，显存占用取决于模型本身，与 Skill 无关。

脚本执行层：格式化脚本本身非常轻量，处理一份 100KB 的 Markdown 文档，耗时通常在毫秒级，内存占用可以忽略。真正重的场景是“批量任务”里需要先调用模型生成内容，再调用格式化脚本；这时主要瓶颈在模型推理，而不是排版。

性能观察建议：第一次跑批量任务时，先拿 10 个文件测试，记录每个文件的模型生成耗时、格式化耗时、总耗时。如果发现格式化耗时异常高（比如单个文件超过 5 秒），说明脚本可能存在性能问题，优先检查是否存在不必要的正则反复匹配，或者文件大小超出脚本预期。

8. 常见问题与排查方法：排版 Skills 落地避坑

这里要特别提醒一个常见的坑：不要在代码块内部执行排版规则。脚本在格式化的过程中，要先识别出代码块，代码块内部的缩进、空格、空行都不能动，否则会破坏代码逻辑。上面示例脚本中没有处理这点，实际使用时要加上代码块保护逻辑。

9. 最佳实践：把排版 Skills 用到工程级水平

基于社区讨论和我自己的工程经验，给出下面几条建议。

第一，规则要少而精。一份 SKILL.md 里的规则如果超过 20 条，模型执行起来就会“顾头不顾尾”。宁可要 10 条能稳定执行的硬规则，也不要 30 条听起来很美但互相冲突的软规则。核心规则放在最前面，模型更容易记住。

第二，模型生成和脚本兜底要分工。模型负责内容组织，脚本负责格式修正。不要指望模型在生成时完美遵守所有规则，而是在生成后跑一遍脚本，把“模型不规范”变成“系统自动规范”。

第三，Skill 要版本化管理。把 SKILL.md、格式化脚本、测试用例都放进 Git 仓库。效果验证通过后，记录当时的模型版本和 Skill 版本。因为模型升级后，同一份 Skill 的效果可能会变化，版本记录能帮你快速定位回归。

第四，批量任务要有可观测性。每次批量处理，生成一份 summary，记录成功数、失败数、平均耗时。下面是简单示例：

# 批量任务运行后输出 summary echo "✅ 成功: 95 个文件" echo "⚠️ 失败: 3 个文件" echo "📋 失败列表: outputs/error_list.md"

不过不要用 emoji，实际项目中用标准文本即可。重要是保留错误日志，方便排查。

第五，注意数据合规。如果 Skill 处理的文本涉及用户隐私、未公开代码、受版权保护的论文，要在本地处理，不要上传到外部模型。如果确实需要模型参与格式化，要确认数据流向和合规边界。

10. 总结：排版 Skills 是 AI 输出质量控制的重要一环

回到 Jason Liu 征集排版 Skills 这个话题。为什么一个搞 LLM 性能优化的人会关心排版？因为 AI 输出质量控制，本质上是一个系统问题。模型能不能写出规范格式，决定了 AI 生成的文档能否直接用于生产、能否批量进入业务流水线、能否被下游工具稳定解析。排版 Skills 看起来只是“让输出好看一点”，实际上是“让 AI 输出具备工业可用性”的基础设施。

这篇文章写了排版 Skills 的设计思路、SKILL.md 写法、Python 格式化脚本、API 封装、批量任务和排查清单。如果你当前被模型输出的格式问题困扰，建议最先验证的是：把 SKILL.md 接入你的 Claude Code 或 Codex 工具，跑一遍测试用例，重点看表格、代码块、中英文空格这三类最影响阅读体验的项。最容易踩的坑是“规则写太多反而失效”，所以第一条建议就是先保持规则精简。

后续可以继续扩展的方向包括：把排版 Skills 与 PDF 生成、PPT 结构、论文 LaTeX 模板结合；为不同业务场景定制多套 Skill 配置；把格式化服务做成团队统一的基础设施，接入内部文档系统。排版这件事做好了，AI 生成内容的可用性会直接上一个台阶。建议收藏备用，尤其当你开始做批量文档生成或搭建 Agent 工作流时，这套思路会帮你省掉很多返工时间。