SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场product-documentation

product-documentation

写作与研究

查看项目

更新于 10-16 06:10

技能介绍

用途

该技能提供一套系统化方法，用于审查和现代化 Agent OS 产品文档，主要涉及三个文件：mission.md（使命）、tech-stack.md（技术栈）和 roadmap.md（路线图）。目标是确保文档具备可量化的价值主张、符合 workspace-hub 标准，并体现工程领域的差异化。

适用时机

  • 为新仓库初始化 Agent OS 产品文档
  • 审查既有产品文档以寻找改进点
  • 确保符合 workspace-hub 标准（UV、Plotly、文件组织）
  • 为产品文档添加可量化指标与成功标准
  • 将技术栈现代化为当前最佳实践
  • 记录模块化架构决策

主要能力

1. 使命文档审查与增强

针对 mission.md 的检查清单包括：

  • 推介部分：包含可量化声明（如“减少 70% 开销”）、明确目标用户与具体痛点、用一句话说明价值主张、使用主动且以收益为导向的语言。
  • 用户画像：包含年龄范围与角色、业务背景（项目数量、团队规模等）、带时间/成本影响的具体可衡量痛点、带成功标准的具体目标。
  • 关键功能：每项功能包含影响指标或时间节省、按类别分组（核心、协作、集成）、从用户收益而非技术实现角度撰写。
  • 成功指标部分（必需）：效率收益（具体时间缩减）、业务影响（金额节省）、采用成功（时间线与满意度指标），所有指标可衡量且可实现。
  • 实施方法部分（必需）：分阶段方法与明确时间线、每阶段即时价值交付、零业务中断策略、可手动覆盖。

2. 技术栈现代化

针对 tech-stack.md 的检查清单包括：

  • 核心技术：使用 UV 包管理器（workspace-hub 标准），而非 Conda/Poetry；指定 Python 3.11+ 与现代类型提示；依赖使用当前主版本（如 Pandas 2.0+）；替换已弃用库（如用 pypdf 替代 PyPDF2）。
  • 可视化标准：所有可视化必须使用 Plotly；明确注明“所有可视化必须为交互式（Plotly）”；不使用 Matplotlib、seaborn 或静态图片导出；Kaleido 仅用于从交互式 Plotly 图表导出静态文件。
  • 模块化架构：反映 decisions.md 的模块化设计（如 DEC-003）；每个模块有清晰 CLI 命令（如 invoice-gen、tax-prep）；明确列出共享组件；清晰定义模块边界。
  • 完整依赖：包含完整 pyproject.toml 配置；覆盖数据处理、文档生成、可视化、邮件、自动化、日志、CLI、测试等类别；开发依赖分离（[project.optional-dependencies]）；定义入口脚本（[project.scripts]）。
  • CLI 接口：指定 Click 或 Typer 框架；为每个模块提供命令示例；包含选项文档；演示使用模式。
  • 测试策略：指定覆盖率要求（最低 80%，关键模块 95%）；记录测试结构（unit/、integration/、performance/）；提供测试命令。
  • 开发环境：UV 安装说明；虚拟环境创建步骤；跨平台支持（Windows/macOS/Linux）；编辑器推荐。

3. 标准合规验证

  • UV 包管理器：正确用法为 uv venv、source .venv/bin/activate（Windows 为 .venv\Scripts\activate）、uv pip install -e .；错误用法为 conda create -n myenv、pip install -r requirements.txt。
  • 交互式可视化：正确用法为使用 plotly.express 生成图表并 fig.write_html('../reports/analysis.html')；错误用法为使用 Matplotlib 生成静态 PNG。
  • 文件组织：报告放在 /reports/ 目录；数据放在 /data/（raw/、processed/、results/）；不向根目录保存文件；源码按模块组织在 /src/。
  • CSV 数据导入：使用相对于报告位置的相对路径；不使用硬编码绝对路径；标准化数据目录结构。

4. 量化框架

提供时间节省、成本节省与采用时间线的计算示例。例如：发票处理从每张 15 分钟降至 2 分钟，每月 10 张，减少 130 分钟/月，即 87% 时间节省；按 75 美元/小时计算，年节省约 1,950 美元/用例，三个用例合计约 5,850 美元/年，加上会计费用减少 2,000-5,000 美元/年，总计 15,000-25,000 美元/年。采用时间线示例：第 1-2 周初始设置与首张自动发票，第 3-4 周费用跟踪自动化，第 5-8 周完整税务准备集成，8 周完成全面采用。

5. 工程领域差异化

面向工程公司时强调：基于项目的计费、技术工时跟踪、多客户并行项目管理、工程服务特定费用类别（认证、软件许可、标准）、专业工程合规跟踪。

使用方式

实施流程分为五步：

  1. 阅读当前文档：cat .agent-os/product/mission.md、cat .agent-os/product/tech-stack.md、cat .agent-os/product/decisions.md。
  2. 对照标准审查：与 workspace-hub 标准比较、检查已弃用技术、验证可量化指标、确保模块化架构已记录。
  3. 提出改进建议：按类别组织、按影响排序、提供具体示例、包含每项变更的理由。
  4. 实施变更：使用 Edit 操作精确修改、更新版本号与日期、保持文档结构、与 decisions.md 交叉引用。
  5. 验证合规：确认使用 UV、确认所有可视化使用 Plotly、检查模块化架构一致性、确保包含可量化指标。

在 Claude Code 或 AI 代理中的示例用法：

  • “审查 mission.md 文件，按照 Product Documentation Modernization 技能提出改进建议。重点添加可量化指标和工程特定价值主张。”
  • “审查 tech-stack.md 是否符合 workspace-hub 标准。将 Conda 替换为 UV，确保 Plotly 为强制项，并添加完整的 pyproject.toml 配置。”

成功标准

文档成功现代化需满足：

  • mission.md：包含 3 个以上可量化效率收益、金额化业务影响指标、完整成功指标部分、实施方法部分、工程特定差异化。
  • tech-stack.md：使用 UV 包管理器（非 Conda）、Plotly 强制并明确注明、包含完整 pyproject.toml、记录模块化架构、所有模块有 CLI 命令、测试策略含覆盖率要求、包含开发环境设置。
  • 两份文档：版本更新（如 1.0.0 → 2.0.0）、日期更新为当前、与 decisions.md 交叉引用、无已弃用技术、无 workspace-hub 标准违规。

限制

该技能为文档审查与现代化流程指南，不包含自动化执行脚本；具体指标数值、成本节省金额与采用时间线需根据实际项目情况计算，资料中提供的数值仅为示例。相关技能包括文件组织技能、标准合规技能、量化技能与 Agent OS 初始化技能。参考资料涉及 workspace-hub 标准路径、Agent OS 指令、UV 包管理器（https://github.com/astral-sh/uv）与 Plotly 文档（https://plotly.com/python/）。版本历史：1.0.0（2026-01-08）基于 aceengineer-admin 的 mission.md 与 tech-stack.md 现代化工作创建。