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 的核心能力大致如下能力项说明解决的核心问题AI 输出内容格式混乱包括 Markdown 层级不清、表格错位、代码块无语言标注、中文排版不规范实现原理通过 SKILL.md 指令 脚本/模板 规则约束让模型在生成文本时调用固定排版规范适用模型支持具备工具调用/Function Calling/Agent 能力的大模型如 Claude 系列、GPT 系列、Codex、DeepSeek 等落地方式可接入 Claude Code、Codex CLI、opencode、Cursor 等支持 Agent/Skills 的编程工具硬件要求无特殊要求Skills 本身是软件层规则不依赖 GPU但如果配合本地模型做验证则需要对应推理硬件是否支持批量任务支持。排版 Skills 可作用于单个文件也可以批量处理整个目录是否支持 API 接口支持。Skill 核心理念是“规则 代码”可以封装成 HTTP 服务供业务系统调用典型输出形态规范化 Markdown、结构清晰的标题树、带语言标签的代码块、对齐的表格、符合中文排版规范的段落适合人群AI 应用开发、Agent 开发者、提示词工程师、需要批量生成文档/代码/PPT 材料的写作者从这张表能看出排版 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 CodeAnthropic 官方 CLI 工具支持自定义 Skills可以参考 Claude Code Skills 官方文档部署。Codex CLIOpenAI 的编程 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(encodingutf-8) formatted format_markdown(text) output_path.write_text(formatted, encodingutf-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 测试维度与预期结果测试用例输入示例预期结果标题层级## 一级后直接#### 三级输出中不会出现跳级标题中英文空格使用AI工具输出变为使用 AI 工具代码块标注无标注的自动补为text或按内容识别为特定语言表格对齐表头与内容列数不一致输出表格列数统一列表结构无序列表与有序列表混用输出统一使用-或1.格式段落间距段间无空行输出自动补充空行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(titleMarkdown Format Service) class FormatRequest(BaseModel): content: str style: str chinese-markdown # 可选扩展风格 class FormatResponse(BaseModel): content: str app.post(/api/format, response_modelFormatResponse) async def format_content(req: FormatRequest): if not req.content.strip(): raise HTTPException(status_code400, detail内容不能为空) formatted format_markdown(req.content) return FormatResponse(contentformatted) if __name__ __main__: uvicorn.run(app, host127.0.0.1, port8760)启动服务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 这类云端模型本地不需要 GPUSkill 上消耗的 token 主要是读取 SKILL.md 的成本。一份 SKILL.md 大概 500 到 1500 个 token对长任务来说占比不高。如果用的是本地模型显存占用取决于模型本身与 Skill 无关。脚本执行层格式化脚本本身非常轻量处理一份 100KB 的 Markdown 文档耗时通常在毫秒级内存占用可以忽略。真正重的场景是“批量任务”里需要先调用模型生成内容再调用格式化脚本这时主要瓶颈在模型推理而不是排版。性能观察建议第一次跑批量任务时先拿 10 个文件测试记录每个文件的模型生成耗时、格式化耗时、总耗时。如果发现格式化耗时异常高比如单个文件超过 5 秒说明脚本可能存在性能问题优先检查是否存在不必要的正则反复匹配或者文件大小超出脚本预期。8. 常见问题与排查方法排版 Skills 落地避坑问题现象可能原因排查方式解决方案模型没有调用 SkillSkill 目录配置错误或名称不匹配检查 Skills 目录路径、文件名是否为 SKILL.md按工具文档调整目录结构确认 Skill 名称与调用名称一致输出格式仍然混乱SKILL.md 规则冲突或过于笼统检查规则是否存在矛盾例如“标题前必须空行”和“标题前不能有空行”并存精简规则只保留最核心的排版本要求中英文空格没加上脚本未被执行或模型输出不在脚本处理路径上检查批量脚本是否覆盖了对应目录把脚本作为后处理兜底而不是依赖模型自觉表格列数不一致输入内容本身缺少分隔符检查原始文本的表格结构在 SKILL.md 中增加“表格列数统一”约束脚本兜底对齐批量任务卡住单文件异常导致任务队列阻塞查看日志定位卡住的文件增加超时重试机制异常文件单独隔离API 调用超时同步接口处理大文本耗时过长用 curl 测试大文件耗时改用异步任务队列或限制单次请求最大字符数显存占用过高本地模型推理导致与 Skill 无关查看 GPU 显存监控降低模型规模或改用云模型接口输出内容被意外修改格式化脚本正则误伤对比格式化前后的 diff调整正则规则增加白名单机制对代码块内容跳过处理这里要特别提醒一个常见的坑不要在代码块内部执行排版规则。脚本在格式化的过程中要先识别出代码块代码块内部的缩进、空格、空行都不能动否则会破坏代码逻辑。上面示例脚本中没有处理这点实际使用时要加上代码块保护逻辑。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 工作流时这套思路会帮你省掉很多返工时间。