| name | product-content-audit |
| description | 从普通用户视角审视代码仓库中的用户可见文案和内容(不是运行中网站测试):页面文案、 按钮、空状态、错误提示、邮件模板、i18n、meta/SEO、CTA 和下载/升级/帮助入口。 当用户要求改文案、清理产品内容、把开发者语言改成人话、检查页面是否跟最近功能同步、 找缺失入口、做 SEO/meta 检查,或定期跑产品内容审查时触发。优先用于 AI 快速迭代、 文案常常落后于代码的小型产品和 side project。
|
Product Content Audit
代码迭代得越快,页面上的文字就越容易过时;开发者写的初版文案,对真实用户来说也常常太硬。这个 skill 的目的是定期帮一个资深开发者、但产品/运营经验有限的用户,从普通用户视角检查仓库里的所有面向用户文案,并按用户确认后再动手修改。
如果用户希望的是手动测试一个跑起来的网站,请改用 website-operator-qa。如果是代码层面的清理重构,请改用 code-maintenance。本 skill 关注的是仓库里那些会被用户看见的字符串:页面文案、按钮、空状态、错误提示、邮件模板、meta 标签、i18n 文件等。
Core Stance
- 把自己当成一个第一次访问、不懂技术的潜在用户,不是写代码的人。看到"dispatch / build / endpoint / token / instance / hydration"会感到困惑甚至害怕,要默认把这些词识别为问题。
- 优先解决会让真实用户看不懂、做不下去、找不到下一步的问题,而不是排版上的小瑕疵。
- 默认两阶段工作:先生成审查报告交给用户确认,再根据被确认的条目修改文件。除非用户明确说"直接改",否则不要在第一阶段动任何源文件。
- 保留品牌语气。能否口语化是一回事;项目原本是面向哪类用户、用什么腔调说话,由用户决定,不要擅自统一风格。
- 不翻译,只校文。多语言项目里,每种语言面向不同的人群,不同语言里的"地道"可能完全不一样;遇到拿不准的地方记下来交给用户决定,不要凭机器翻译直接同步。
Workflow
下面是默认的两阶段流程。第一阶段产出报告并等待用户确认,第二阶段根据被批准的条目动手修改。除非用户明确说"跳过报告、直接改",否则永远先做第一阶段。
Phase 0 — Build context
不管接下来跑哪一阶段,都先读这些再开工,跳过会导致改错或者重复别人已经定过的事:
README.md — 产品定位、目标用户、当前阶段(alpha / beta / 上线了多久),决定我们要不要"贴近小白"还是"贴近开发者"。
DEV_NOTE.md / ARCHITECTURE.md 等架构说明 —— 团队对产品语言的既有约定(专有名词、品牌词、要不要保留某些技术词)。
package.json — 框架(Next.js / Nuxt / Vite / Astro 等)以及是否使用 i18n 库(next-intl, vue-i18n, react-i18next, paraglide, nuxt-i18n 等),用来定位文案文件。
- 如果有
BRAND.md / VOICE.md / STYLEGUIDE.md —— 一定要读,覆盖默认语气。
- 项目里现有的
locales/、messages/、i18n/、lang/ 等目录 —— 即便没有显式声明也能找出来。
定位用户可见文案,常见但不限于的位置(按命中概率从高到低):
- i18n 资源:
locales/*.json、messages/*.json、i18n/**/*.{json,ts,yaml}
- 页面:
app/**、pages/**、src/views/**、src/routes/**、src/pages/**
- 组件:
components/**、src/components/**(特别是 Hero、Pricing、Footer、EmptyState、ErrorState 这类)
- 元数据 / SEO:
app/layout.*、pages/_document.*、<head> 配置文件、sitemap、robots、og-image 模板、manifest.json
- 邮件模板:
emails/**、templates/**、mail/**
- 静态资源:
public/、docs/、marketing/、landing/
如果同一字符串既出现在 i18n 文件里,也出现在组件里,以 i18n 文件为准,先改 i18n 资源;只有当组件里的硬编码文本绕过 i18n 时,才改组件。
Phase 1 — Audit (report only)
目标:扫一遍仓库,输出一份审查报告,不修改任何源文件。
-
理解最近的代码变化
- 读最近 N 次提交(默认 30 次或一周内,看哪个先到):
git log --no-merges -n 30 --pretty=format:"%h %s",再 git log -p / git show 看具体改动。
- 重点关注:新功能、改名、删除的功能、参数/选项变化、价格/计划变化、登录/注册流程变化。这些是最容易让页面文案过时的改动。
- 用一句普通用户能听懂的话,给每条值得关注的提交写一个"这次改的是什么"。如果用户看不懂提交标题里的术语,那 commit message 本身可能也需要改进,但这是另一回事,先记下来。
-
建立全部用户可见文案的清单
- 不要逐字符检查每个文件。用一组关键字快速过一遍:
- 技术词捕捉:
dispatch|hydrat|render|endpoint|token|instance|namespace|webhook|payload|stdout|throttle|polling|OAuth|JWT|CORS|SSR|CSR|cron|cli|backend|frontend|API\s*key
- 占位符提示:
TODO|FIXME|TBD|Lorem|placeholder|coming soon(这些词被遗忘出现在生产文案里是常见事故)
- 未本地化的硬编码:在主要语言为中文的项目里搜大段英文,反之亦然
- 发现疑似命中后再去看完整上下文,不要只凭关键字下判断。
-
逐项检查(参考清单)
完整清单见 references/checklist.md。最低限度要覆盖:
- 首页 / 着陆页 hero 文案是否还和当前实际功能一致
- 仪表盘 / 控制台关键页面是否包含下一步入口:下载 / 升级 / 文档 / 联系 / 帮助
- 空状态、加载状态、错误状态文案是否对普通用户友好
- 主要按钮 label 是否能让用户在不读上下文的情况下大致知道会发生什么
- meta
title / description / og:* 是否齐备且面向用户而不是开发者
- 多语言项目中,所有 locale 是否覆盖了同一组 key
-
把技术黑话改写指南映射到本项目
-
写出审查报告
- 报告格式见 references/audit-report.md。
- 默认保存到
WIP/product-content-audit-YYYY-MM-DD.md(如果项目没有 WIP/ 目录就放到仓库根目录,并提醒用户加到 .gitignore)。
- 报告里每个条目都要带一个唯一 ID(如
J1、L2),方便用户在第二阶段说"批准 J1、J3、L2,跳过 J2"。
-
报告完成后停下,把路径告诉用户,等他确认。 不要主动进入 Phase 2。
Phase 2 — Apply approved changes
只有用户明确说"开始改"或者"按报告改 X、Y、Z"之后,才进入这一阶段。
-
读取上一阶段的报告
- 默认读
WIP/ 目录下最新的 product-content-audit-*.md。
- 如果用户没特别说,默认应用所有标记为强烈建议的条目,跳过待商榷的条目。
-
逐条修改,每条独立成可识别的最小改动
- 一个条目对应一组相关字符串的修改,而不是顺手把整块组件重写。
- 命中 i18n 文件时,先改默认语言(通常是 README 里写的产品主语言),把其他语言里同一个 key 的文本一起列出来给用户看,由他确认是否需要同步更新;不要直接帮他翻译。
- 改的时候不要顺手:
- 改组件结构(比如把
<p> 改成 <div>)
- 调样式、颜色、间距
- 重命名 i18n key
- 删除/添加路由
这些都不在本 skill 的职责内,会带来超出预期的副作用。
-
遇到下面这些情况,停下来问用户
- 改动会改变品牌专有名词(例如把 "Resume" 改成 "CV")
- 改动会影响转化路径(例如改写 CTA 按钮文字)
- 同一个 key 在多个 locale 里语义不一致,无法判断哪个才是"真版本"
- 报告里某条建议在实际上下文里不再适用(这种情况要更新报告而不是硬改)
-
结束时给一份变更摘要
- 改了哪些文件、共多少处、按报告 ID 列出已应用 / 已跳过 / 因为 X 没改。
- 列出 i18n 中被新增或修改的 key,方便用户做翻译记忆。
- 提醒用户跑一遍
website-operator-qa,从用户角度复核改动效果。
What To Look For
下面是判断"该不该改"的原则速查。详细清单见 references/checklist.md。
- 技术黑话渗入用户视野:英文术语原样出现在按钮、说明、错误提示里;中英混用且英文部分是技术词;缩写没有展开(API、SSR、CMS、PWA 等)。
- 文案落后于代码:最近 commit 里加 / 改 / 删了功能,但相关页面还在描述老行为;价格变了但定价页没改;新增了一个登录方式但首页 CTA 还是只提一种。
- 关键页面缺下一步:dashboard 没有"下载客户端 / 升级 / 联系我们 / 看文档"的入口;空状态只有一个图标和"暂无数据",没有任何引导;错误状态只说"出错了",没有任何让用户继续的方式。
- SEO / 元信息漏洞:title 是
Untitled / 文件名 / 框架默认值;description 是 lorem 或开发笔记;缺 og:image / og:title;同一 locale 缺整段 meta。
- 可读性问题:单段超过 5 行;长句套长句;按钮 label 是名词或动词原型,看不出会发生什么("提交"、"确认"在缺乏上下文时含义模糊);占位符 / TODO / coming soon 漏到生产环境。
- i18n 不齐:某些 locale 缺 key;不同 locale 的同一 key 语义偏差大;新加的功能只翻译了一种语言。
Severity Heuristic
报告里每条问题都标一个严重度,方便用户取舍。
- 高:会让真实用户在第一次访问时看不懂、找不到入口、放弃使用。例:注册按钮在某个 locale 里写的是错的语言;dashboard 上没有下载产品的入口;首页 hero 描述的是已经下线的功能。
- 中:不影响"能不能用",但会降低信任、影响转化或 SEO。例:meta description 是开发占位文本;定价页价格已经变了但页面没改;FAQ 里仍然提及一个废弃功能。
- 低:打磨级。例:某个空状态的措辞稍微生硬;按钮 label 可以更友好但不会被误解;某个 locale 的标点不统一。
严重度永远用业务语言解释,不要只给技术分类。
Guardrails
- 不修改产品立场和品牌词。"我们的"、"专业"、"AI"等是否使用,由用户决定。
- 不顺手修代码 bug。看见 bug 就记到报告里,不在本 skill 中修复。
- 不动测试 / 内部文档 / commit message / PR 模板。这些不是面向用户的内容。
- 不引入新依赖、不重构组件、不重命名 i18n key。改动只发生在字符串层面。
- 不要替用户翻译。多语言不齐时,先标记,让用户决定怎么处理。
- 不删除内容。即使建议把某段文案删掉,也要在报告里说明,等用户确认。
- 不把 audit 报告 commit 进 main 分支,除非用户明确要求。默认放在
WIP/ 或被 .gitignore 的目录。
When To Suggest Other Skills
跑完审查后如果发现下列情况,建议用户切换或并行使用其他 skill:
- 看到"页面挂了 / 链接 404 / 表单提交后没反应"——切换到
website-operator-qa 做一次浏览器侧的复核。
- 看到大量 TODO / FIXME / 巨型组件——切换到
code-maintenance 做代码侧清理。
- 看到 commit message 本身就让人看不懂——这不是本 skill 的职责,但可以提醒用户考虑写一份团队 commit 规范。