Back to Details

product-documentation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Product Documentation Modernization Skill

产品文档现代化Skill

Version: 1.0.0 Created: 2026-01-08 Category: Documentation, Product Management, Standards Compliance
版本：1.0.0 创建时间：2026-01-08 分类：文档、产品管理、标准合规

Overview

概述

This skill provides a systematic approach to reviewing and modernizing Agent OS product documentation (mission.md, tech-stack.md, roadmap.md) to ensure quantifiable value propositions, workspace-hub standards compliance, and engineering-specific differentiation.
本Skill提供了一套系统化的方法来审核和现代化Agent OS产品文档（mission.md、tech-stack.md、roadmap.md），确保文档具备可量化的价值主张、符合workspace-hub标准，并体现工程领域的差异化特性。

When to Use

适用场景

Use this skill when:
  • Initializing Agent OS product documentation for new repositories
  • Reviewing existing product documentation for improvements
  • Ensuring compliance with workspace-hub standards (UV, Plotly, file organization)
  • Adding quantifiable metrics and success criteria to product documents
  • Modernizing technology stacks to current best practices
  • Documenting modular architecture decisions
在以下场景中使用本Skill：
  • 为新代码库初始化Agent OS产品文档
  • 审核现有产品文档以寻求改进空间
  • 确保文档符合workspace-hub标准（UV、Plotly、文件组织规范）
  • 为产品文档添加可量化指标和成功标准
  • 按照当前最佳实践现代化技术栈
  • 记录模块化架构决策

Skill Components

Skill组件

1. Mission Document Review & Enhancement

1. 使命文档审核与增强

Checklist for mission.md:
Pitch Section:
  • Includes quantifiable claim (e.g., "reduces overhead by 70%")
  • Clearly states target users and specific pain point
  • Explains value proposition in one sentence
  • Uses active, benefit-focused language
User Personas:
  • Includes age range and role
  • Defines business context (number of projects, team size, etc.)
  • Lists specific, measurable pain points with time/cost impacts
  • States concrete goals with success criteria
Example:
markdown
**Business Administrator** (28-45 years old)
- **Role:** Administrative Manager or Business Operations Coordinator
- **Context:** Day-to-day management of business finances, invoicing, and compliance for 3-7 concurrent engineering projects
- **Pain Points:**
  - Spending 6-8 hours/week on invoice generation across multiple clients
  - Manual expense categorization from credit card statements (2-3 hours/week)
  - Annual tax preparation requires 20-30 hours of document organization
- **Goals:**
  - Reduce administrative time by 70% to focus on business development
  - Achieve 100% on-time invoice delivery (currently 75%)
Key Features:
  • Each feature includes impact metrics or time savings
  • Features grouped by category (Core, Collaboration, Integration)
  • Features written from user benefit perspective, not technical implementation
Success Metrics Section (Required):
  • Efficiency Gains: Specific time reductions (e.g., 85% reduction in invoice time)
  • Business Impact: Dollar savings (e.g., $15K-25K annually)
  • Adoption Success: Timeline and satisfaction metrics
  • All metrics are measurable and achievable
Implementation Approach Section (Required):
  • Phased approach with clear timelines
  • Each phase shows immediate value delivery
  • Zero business disruption strategy
  • Manual override availability
mission.md审核清单：
价值主张部分：
  • 包含可量化的声明（例如：“将运维开销降低70%”）
  • 清晰说明目标用户和具体痛点
  • 用一句话阐述价值主张
  • 使用主动语态、聚焦收益的语言
用户角色：
  • 包含年龄范围和职位角色
  • 定义业务背景（项目数量、团队规模等）
  • 列出具体、可衡量的痛点及时间/成本影响
  • 明确带有成功标准的具体目标
示例：
markdown
**业务管理员**（28-45岁）
- **职位：** 行政经理或业务运营协调员
- **背景：** 日常管理3-7个并行工程项目的财务、发票和合规事务
- **痛点：**
  - 每周花费6-8小时为多个客户生成发票
  - 手动从信用卡账单中分类费用（每周2-3小时）
  - 年度税务准备需要20-30小时整理文档
- **目标：**
  - 将行政工作时间减少70%，专注于业务拓展
  - 实现100%的发票按时交付（当前为75%）
核心功能：
  • 每个功能都包含影响指标或时间节省数据
  • 功能按类别分组（核心功能、协作功能、集成功能）
  • 从用户收益角度而非技术实现角度描述功能
成功指标部分（必填）：
  • 效率提升：具体的时间减少比例（例如：发票处理时间减少85%）
  • 业务影响：成本节省金额（例如：每年1.5万-2.5万美元）
  • 采用情况：时间线和满意度指标
  • 所有指标均可衡量且可实现
实施方法部分（必填）：
  • 分阶段实施，时间线清晰
  • 每个阶段都能交付即时价值
  • 零业务中断策略
  • 支持手动覆盖操作

2. Tech Stack Modernization

2. 技术栈现代化

Checklist for tech-stack.md:
Core Technologies:
  • Uses UV package manager (workspace-hub standard) - NOT Conda/Poetry
  • Python 3.11+ specified with modern type hints
  • All dependencies use current major versions (e.g., Pandas 2.0+, not 1.x)
  • Deprecated libraries replaced (e.g., pypdf instead of PyPDF2)
Visualization Standards:
  • Plotly MANDATORY for all visualizations
  • Explicit note: "All visualizations MUST be interactive (Plotly)"
  • NO Matplotlib, seaborn, or static image exports
  • Kaleido for static exports FROM interactive Plotly charts only
Modular Architecture:
  • Reflects decisions.md modular design (e.g., DEC-003)
  • Each module has clear CLI command (e.g., 
    invoice-gen
    , 
    tax-prep
    )
  • Shared components explicitly listed
  • Module boundaries clearly defined
Complete Dependencies:
  • Full pyproject.toml configuration included
  • All categories covered: data processing, document generation, visualization, email, automation, logging, CLI, testing
  • Development dependencies separated (
    [project.optional-dependencies]
    )
  • Entry point scripts defined (
    [project.scripts]
    )
CLI Interface:
  • Click or Typer framework specified
  • Command examples for each module
  • Option documentation included
  • Usage patterns demonstrated
Testing Strategy:
  • Coverage requirements specified (minimum 80%, critical modules 95%)
  • Test structure documented (unit/, integration/, performance/)
  • Testing commands provided
Development Environment:
  • UV installation instructions
  • Virtual environment creation steps
  • Cross-platform support (Windows/macOS/Linux)
  • Editor recommendations
tech-stack.md审核清单：
核心技术：
  • 使用UV包管理器（workspace-hub标准）- 禁止使用Conda/Poetry
  • 指定Python 3.11+版本并使用现代类型提示
  • 所有依赖项使用当前主要版本（例如：Pandas 2.0+，而非1.x）
  • 替换已弃用的库（例如：用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. Standards Compliance Verification

3. 标准合规验证

Workspace-Hub Standards:
UV Package Manager:
bash
undefined
Workspace-Hub标准：
UV包管理器：
bash
undefined

✅ Correct

✅ 正确用法

uv venv source .venv/bin/activate # On Windows: .venv\Scripts\activate uv pip install -e .
uv venv source .venv/bin/activate # Windows系统使用：.venv\Scripts\activate uv pip install -e .

❌ Wrong

❌ 错误用法

conda create -n myenv pip install -r requirements.txt

**Interactive Visualizations:**
```python
conda create -n myenv pip install -r requirements.txt

**交互式可视化：**
```python

✅ Correct - Plotly interactive

✅ 正确用法 - Plotly交互式

import plotly.express as px fig = px.scatter(df, x='time', y='value') fig.write_html('../reports/analysis.html')
import plotly.express as px fig = px.scatter(df, x='time', y='value') fig.write_html('../reports/analysis.html')

❌ Wrong - Matplotlib static

❌ 错误用法 - Matplotlib静态

import matplotlib.pyplot as plt plt.scatter(df['time'], df['value']) plt.savefig('plot.png')

**File Organization:**
- [ ] Reports in `/reports/` directory
- [ ] Data in `/data/` (raw/, processed/, results/)
- [ ] No files saved to root folder
- [ ] Module-based source organization in `/src/`

**CSV Data Import:**
- [ ] Uses relative paths from report location
- [ ] No hardcoded absolute paths
- [ ] Standardized data directory structure
import matplotlib.pyplot as plt plt.scatter(df['time'], df['value']) plt.savefig('plot.png')

**文件组织：**
- [ ] 报告文件存放在`/reports/`目录
- [ ] 数据文件存放在`/data/`（raw/、processed/、results/）
- [ ] 根目录下不保存文件
- [ ] 源代码按模块组织在`/src/`目录

**CSV数据导入：**
- [ ] 使用相对于报告位置的相对路径
- [ ] 不使用硬编码的绝对路径
- [ ] 采用标准化的数据目录结构

4. Quantification Framework

4. 量化框架

Adding Metrics to Documents:
Time Savings Calculation:
Before: 15 minutes per invoice × 10 invoices/month = 150 minutes/month
After: 2 minutes per invoice × 10 invoices/month = 20 minutes/month
Reduction: 130 minutes/month = 87% time savings
Cost Savings Calculation:
Hourly rate: $75/hour
Time saved: 130 minutes/month × 12 months = 1,560 minutes/year = 26 hours/year
Value: 26 hours × $75 = $1,950/year per use case

Total across 3 use cases: ~$5,850/year
Add accountant fee reduction: $2,000-5,000/year
Total: $15,000-25,000/year
Adoption Timeline:
Week 1-2: Initial setup and first automated invoice
Week 3-4: Expense tracking automation
Week 5-8: Full tax preparation integration
Result: 8 weeks to full adoption
为文档添加指标：
时间节省计算：
之前：每张发票15分钟 × 每月10张发票 = 每月150分钟
之后：每张发票2分钟 × 每月10张发票 = 每月20分钟
减少：每月130分钟 = 节省87%的时间
成本节省计算：
小时费率：75美元/小时
节省的时间：每月130分钟 × 12个月 = 每年1560分钟 = 每年26小时
价值：26小时 × 75美元 = 每个用例每年1950美元

3个用例总计：约每年5850美元
加上会计师费用减少：每年2000-5000美元
总计：每年15000-25000美元
采用时间线：
第1-2周：初始设置和首张自动化发票
第3-4周：费用跟踪自动化
第5-8周：完整税务准备集成
结果：8周实现全面采用

5. Engineering-Specific Differentiation

5. 工程领域差异化

For Engineering Firms:
  • Project-based billing emphasized
  • Technical hours tracking mentioned
  • Multi-client parallel project management
  • Engineering service-specific expense categories (certifications, software licenses, standards)
  • Professional engineering compliance tracking
Example Differentiator:
markdown
undefined
针对工程公司：
  • 强调基于项目的计费方式
  • 提及技术工时跟踪
  • 多客户并行项目管理
  • 工程服务特定的费用分类（认证、软件许可、标准合规）
  • 专业工程合规跟踪
差异化示例：
markdown
undefined

Engineering Project Financial Tracking

工程项目财务跟踪

Unlike generic accounting systems, we provide project-based billing with technical hours tracking, multi-client parallel project management, and engineering service-specific expense categorization (design software, certifications, industry standards). This results in accurate project profitability analysis and improved resource allocation for engineering teams.
undefined
与通用会计系统不同，我们提供基于项目的计费方式，包含技术工时跟踪、多客户并行项目管理，以及工程服务特定的费用分类（设计软件、认证、行业标准）。这能够为工程团队提供准确的项目盈利能力分析，优化资源分配。
undefined

Implementation Process

实施流程

Step 1: Read Current Documentation

步骤1：读取当前文档

bash
undefined
bash
undefined

Read all three product documents

读取所有三个产品文档

cat .agent-os/product/mission.md cat .agent-os/product/tech-stack.md cat .agent-os/product/decisions.md
undefined
cat .agent-os/product/mission.md cat .agent-os/product/tech-stack.md cat .agent-os/product/decisions.md
undefined

Step 2: Review Against Standards

步骤2：对照标准审核

  • Compare against workspace-hub standards
  • Check for deprecated technologies
  • Verify quantifiable metrics exist
  • Ensure modular architecture documented
  • 与workspace-hub标准进行对比
  • 检查是否存在已弃用的技术
  • 验证是否包含可量化指标
  • 确认模块化架构已记录

Step 3: Suggest Improvements

步骤3：提出改进建议

  • Organize suggestions by category
  • Prioritize based on impact
  • Provide specific examples
  • Include rationale for each change
  • 按类别组织建议
  • 根据影响程度排序优先级
  • 提供具体示例
  • 为每个变更提供理由

Step 4: Implement Changes

步骤4：实施变更

  • Use Edit operations for precision
  • Update version numbers and dates
  • Maintain document structure
  • Cross-reference with decisions.md
  • 使用编辑操作确保精准性
  • 更新版本号和日期
  • 保持文档结构
  • 与decisions.md进行交叉引用

Step 5: Validate Compliance

步骤5：验证合规性

  • Verify UV package manager used
  • Confirm Plotly for all visualizations
  • Check modular architecture alignment
  • Ensure quantifiable metrics included
  • 确认使用UV包管理器
  • 确保所有可视化使用Plotly
  • 检查模块化架构一致性
  • 确保包含可量化指标

Templates

模板

Mission.md Success Metrics Template

Mission.md成功指标模板

markdown
undefined
markdown
undefined

Success Metrics

成功指标

Efficiency Gains

效率提升

  • [Feature]: [%] reduction in time ([before] → [after])
  • [Feature]: [%] reduction in [metric] ([before] → [after])
  • [功能]： [百分比]的时间减少（[之前] → [之后]）
  • [功能]： [百分比]的[指标]减少（[之前] → [之后]）

Business Impact

业务影响

  • Cost Savings: $[amount] annually ([breakdown])
  • Revenue Protection: $[amount] in [area]
  • Risk Reduction: [%] accuracy improvement
  • 成本节省： 每年[金额]美元（[明细]）
  • 收入保障： [领域]的[金额]美元
  • 风险降低： [百分比]的准确性提升

Adoption Success

采用情况

  • Time to First Value: [timeframe]
  • Full System Adoption: [timeframe]
  • User Satisfaction: [measurable outcome]
undefined
  • 首次价值交付时间： [时间范围]
  • 系统全面采用时间： [时间范围]
  • 用户满意度： [可衡量结果]
undefined

Tech-Stack.md pyproject.toml Template

Tech-Stack.md pyproject.toml模板

toml
[project]
name = "project-name"
version = "1.0.0"
description = "Brief description"
requires-python = ">=3.11"
dependencies = [
    # Data Processing
    "pandas>=2.0.0",
    "numpy>=1.24.0",

    # Visualization (Interactive Only)
    "plotly>=5.14.0",
    "kaleido>=0.2.1",

    # CLI Development
    "click>=8.1.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.4.0",
    "pytest-cov>=4.1.0",
    "ruff>=0.1.0",
]

[project.scripts]
module-name = "package.module:main"
toml
[project]
name = "project-name"
version = "1.0.0"
description = "简要描述"
requires-python = ">=3.11"
dependencies = [
    # 数据处理
    "pandas>=2.0.0",
    "numpy>=1.24.0",

    # 可视化（仅支持交互式）
    "plotly>=5.14.0",
    "kaleido>=0.2.1",

    # CLI开发
    "click>=8.1.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.4.0",
    "pytest-cov>=4.1.0",
    "ruff>=0.1.0",
]

[project.scripts]
module-name = "package.module:main"

Example Usage

使用示例

Review Mission Document

审核使命文档

python
undefined
python
undefined

In Claude Code or AI agent

在Claude Code或AI Agent中执行

"Review the mission.md file and suggest improvements following the Product Documentation Modernization skill. Focus on adding quantifiable metrics and engineering-specific value propositions."
undefined
"按照产品文档现代化Skill的要求审核mission.md文件并提出改进建议。重点关注添加可量化指标和工程领域特定的价值主张。"
undefined

Modernize Tech Stack

现代化技术栈

python
undefined
python
undefined

In Claude Code or AI agent

在Claude Code或AI Agent中执行

"Review tech-stack.md for compliance with workspace-hub standards. Replace Conda with UV, ensure Plotly is mandatory, and add complete pyproject.toml configuration."
undefined
"审核tech-stack.md是否符合workspace-hub标准。将Conda替换为UV，确保强制使用Plotly，并添加完整的pyproject.toml配置。"
undefined

Success Criteria

成功标准

Documentation is successfully modernized when:
Mission.md:
  • Includes 3+ quantifiable efficiency gains
  • Contains dollar-value business impact metrics
  • Has complete Success Metrics section
  • Includes Implementation Approach section
  • Features engineering-specific differentiation
Tech-stack.md:
  • Uses UV package manager (not Conda)
  • Plotly mandatory with explicit note
  • Complete pyproject.toml included
  • Modular architecture documented
  • CLI commands for all modules
  • Testing strategy with coverage requirements
  • Development environment setup included
Both Documents:
  • Version updated (e.g., 1.0.0 → 2.0.0)
  • Date updated to current
  • Cross-referenced with decisions.md
  • No deprecated technologies
  • No workspace-hub standard violations
文档现代化成功的标志：
Mission.md：
  • 包含3个以上可量化的效率提升指标
  • 包含美元价值的业务影响指标
  • 包含完整的成功指标部分
  • 包含实施方法部分
  • 体现工程领域的差异化特性
Tech-stack.md：
  • 使用UV包管理器（而非Conda）
  • 强制使用Plotly并明确标注
  • 包含完整的pyproject.toml配置
  • 记录模块化架构
  • 所有模块都有CLI命令
  • 包含带有覆盖率要求的测试策略
  • 包含开发环境设置说明
两类文档通用：
  • 版本号已更新（例如：1.0.0 → 2.0.0）
  • 日期已更新为当前日期
  • 与decisions.md进行交叉引用
  • 无已弃用技术
  • 无违反workspace-hub标准的内容

Related Skills

相关技能

  • File Organization Skill - For organizing documentation and code files
  • Standards Compliance Skill - For verifying workspace-hub standards
  • Quantification Skill - For calculating time and cost savings
  • Agent OS Initialization Skill - For setting up new repositories
  • 文件组织Skill - 用于组织文档和代码文件
  • 标准合规Skill - 用于验证workspace-hub标准合规性
  • 量化Skill - 用于计算时间和成本节省
  • Agent OS初始化Skill - 用于设置新代码库

References

参考资料

Version History

版本历史

  • 1.0.0 (2026-01-08): Initial skill creation based on aceengineer-admin mission.md and tech-stack.md modernization work
  • 1.0.0（2026-01-08）：基于aceengineer-admin的mission.md和tech-stack.md现代化工作创建初始版本