document-xlsx

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Document XLSX Skill — Quick Reference

XLSX文档处理技能——快速参考

This skill enables creation, editing, and analysis of Excel spreadsheets programmatically. Claude should apply these patterns when users need to generate data reports, financial models, automate Excel workflows, or process spreadsheet data.
Modern Best Practices (Jan 2026):
  • Treat spreadsheets as software: clear inputs/outputs, auditability, and versioning.
  • Protect data integrity: control totals, validation, and traceability to sources.
  • Accessibility: labels, contrast, structure; use Excel's Accessibility Checker; meet procurement/regulatory requirements when distributing externally.
  • If distributing in the EU or regulated contexts, follow applicable accessibility requirements (often aligned with EN 301 549 / WCAG).
  • Ship with a review loop and an owner (avoid "mystery models").
  • Security: treat untrusted input/workbooks as hostile (formula injection, external links, hidden content, macros).

本技能支持以编程方式创建、编辑和分析Excel电子表格。当用户需要生成数据报告、财务模型、自动化Excel工作流或处理电子表格数据时,Claude应遵循这些模式。
2026年1月现代最佳实践:
  • 将电子表格视为软件:明确输入/输出、可审核性和版本控制。
  • 保护数据完整性:控制总计、验证和数据源可追溯性。
  • 可访问性:设置标签、对比度和结构;使用Excel的可访问性检查器;向外部分发时满足采购/监管要求。
  • 如果在欧盟或受监管环境中分发,请遵循适用的可访问性要求(通常与EN 301 549 / WCAG对齐)。
  • 附带审核流程和负责人(避免"神秘模型")。
  • 安全性:将不可信的输入/工作簿视为有风险内容(公式注入、外部链接、隐藏内容、宏)。

Quick Reference

快速参考

TaskTool/LibraryLanguageWhen to Use
Create XLSXExcelJSNode.jsReports, data exports
Create XLSXopenpyxlPythonRead/write, modify existing files
Create XLSXXlsxWriterPythonWrite-only, rich formatting, charts
Data analysispandas + openpyxlPythonDataFrame to Excel with formatting
Read XLSXxlsx (SheetJS)Node.jsParse spreadsheets
Chartsopenpyxl/XlsxWriterPythonEmbedded visualizations
StylingExcelJS/openpyxlBothConditional formatting
AutomationxlwingsPythonExcel installed, interactive workflows
任务工具/库语言适用场景
创建XLSX文件ExcelJSNode.js报告、数据导出
创建XLSX文件openpyxlPython读写、修改现有文件
创建XLSX文件XlsxWriterPython仅写入、丰富格式设置、图表
数据分析pandas + openpyxlPython带格式的DataFrame转Excel
读取XLSX文件xlsx (SheetJS)Node.js解析电子表格
图表openpyxl/XlsxWriterPython嵌入式可视化
样式设置ExcelJS/openpyxl两者皆可条件格式
自动化xlwingsPython已安装Excel、交互式工作流

Guardrails and Caveats

注意事项与限制

  • Formula calculation: libraries write formulas; Excel computes results when opened. If you need computed values server-side, calculate in code and write values (or use a dedicated formula engine).
  • Pivot tables: programmatic creation is limited. Prefer pandas summaries (pivot tables as data) or Excel automation (xlwings/Office Scripts/VBA) if you truly need native pivots.
  • Macros: openpyxl can preserve existing VBA (
    keep_vba=True
    ) but does not author macros; never generate or execute macros from untrusted input.
  • Spreadsheet injection: never put untrusted strings into
    formula
    fields; write them as text values and validate/sanitize user-provided data used in exports.

  • 公式计算:库负责写入公式;Excel在打开文件时计算结果。如果需要在服务器端获取计算后的值,请在代码中计算并写入值(或使用专用公式引擎)。
  • 数据透视表:程序化创建功能有限。优先使用pandas生成汇总表(将透视表作为数据);如果确实需要原生透视表,请使用Excel自动化工具(xlwings/Office Scripts/VBA)。
  • 宏:openpyxl可以保留现有VBA(
    keep_vba=True
    )但不支持编写宏;切勿从不可信输入生成或执行宏。
  • 电子表格注入:切勿将不可信字符串写入
    formula
    字段;请将其作为文本值写入,并对导出中使用的用户提供数据进行验证/清理。

Core Operations

核心操作

Create Spreadsheet (Node.js - exceljs)

创建电子表格(Node.js - exceljs)

typescript
import ExcelJS from 'exceljs';

const workbook = new ExcelJS.Workbook();
const sheet = workbook.addWorksheet('Sales Report');

// Headers with styling
sheet.columns = [
  { header: 'Product', key: 'product', width: 20 },
  { header: 'Quantity', key: 'qty', width: 12 },
  { header: 'Price', key: 'price', width: 12 },
  { header: 'Total', key: 'total', width: 15 },
];

// Style header row
sheet.getRow(1).font = { bold: true };
sheet.getRow(1).fill = {
  type: 'pattern',
  pattern: 'solid',
  fgColor: { argb: 'FF4472C4' }
};

// Add data
const data = [
  { product: 'Widget A', qty: 100, price: 10 },
  { product: 'Widget B', qty: 50, price: 25 },
];

data.forEach((item, index) => {
  sheet.addRow({
    product: item.product,
    qty: item.qty,
    price: item.price,
    total: { formula: `B${index + 2}*C${index + 2}` }
  });
});

// Add totals row
const lastRow = sheet.rowCount + 1;
sheet.addRow({
  product: 'TOTAL',
  total: { formula: `SUM(D2:D${lastRow - 1})` }
});

// Currency formatting
sheet.getColumn('price').numFmt = '$#,##0.00';
sheet.getColumn('total').numFmt = '$#,##0.00';

await workbook.xlsx.writeFile('report.xlsx');
typescript
import ExcelJS from 'exceljs';

const workbook = new ExcelJS.Workbook();
const sheet = workbook.addWorksheet('Sales Report');

// Headers with styling
sheet.columns = [
  { header: 'Product', key: 'product', width: 20 },
  { header: 'Quantity', key: 'qty', width: 12 },
  { header: 'Price', key: 'price', width: 12 },
  { header: 'Total', key: 'total', width: 15 },
];

// Style header row
sheet.getRow(1).font = { bold: true };
sheet.getRow(1).fill = {
  type: 'pattern',
  pattern: 'solid',
  fgColor: { argb: 'FF4472C4' }
};

// Add data
const data = [
  { product: 'Widget A', qty: 100, price: 10 },
  { product: 'Widget B', qty: 50, price: 25 },
];

data.forEach((item, index) => {
  sheet.addRow({
    product: item.product,
    qty: item.qty,
    price: item.price,
    total: { formula: `B${index + 2}*C${index + 2}` }
  });
});

// Add totals row
const lastRow = sheet.rowCount + 1;
sheet.addRow({
  product: 'TOTAL',
  total: { formula: `SUM(D2:D${lastRow - 1})` }
});

// Currency formatting
sheet.getColumn('price').numFmt = '$#,##0.00';
sheet.getColumn('total').numFmt = '$#,##0.00';

await workbook.xlsx.writeFile('report.xlsx');

Create Spreadsheet (Python - openpyxl)

创建电子表格(Python - openpyxl)

python
from openpyxl import Workbook
from openpyxl.styles import Font, PatternFill

wb = Workbook()
ws = wb.active
ws.title = 'Sales Report'
python
from openpyxl import Workbook
from openpyxl.styles import Font, PatternFill

wb = Workbook()
ws = wb.active
ws.title = 'Sales Report'

Headers

Headers

headers = ['Product', 'Quantity', 'Price', 'Total'] for col, header in enumerate(headers, 1): cell = ws.cell(row=1, column=col, value=header) cell.font = Font(bold=True, color='FFFFFF') cell.fill = PatternFill(start_color='4472C4', end_color='4472C4', fill_type='solid')
headers = ['Product', 'Quantity', 'Price', 'Total'] for col, header in enumerate(headers, 1): cell = ws.cell(row=1, column=col, value=header) cell.font = Font(bold=True, color='FFFFFF') cell.fill = PatternFill(start_color='4472C4', end_color='4472C4', fill_type='solid')

Data

Data

data = [ ('Widget A', 100, 10), ('Widget B', 50, 25), ('Widget C', 75, 15), ]
for row_idx, (product, qty, price) in enumerate(data, 2): ws.cell(row=row_idx, column=1, value=product) ws.cell(row=row_idx, column=2, value=qty) ws.cell(row=row_idx, column=3, value=price) ws.cell(row=row_idx, column=4, value=f'=B{row_idx}*C{row_idx}')
data = [ ('Widget A', 100, 10), ('Widget B', 50, 25), ('Widget C', 75, 15), ]
for row_idx, (product, qty, price) in enumerate(data, 2): ws.cell(row=row_idx, column=1, value=product) ws.cell(row=row_idx, column=2, value=qty) ws.cell(row=row_idx, column=3, value=price) ws.cell(row=row_idx, column=4, value=f'=B{row_idx}*C{row_idx}')

Totals row

Totals row

total_row = len(data) + 2 ws.cell(row=total_row, column=1, value='TOTAL') ws.cell(row=total_row, column=4, value=f'=SUM(D2:D{total_row-1})')
total_row = len(data) + 2 ws.cell(row=total_row, column=1, value='TOTAL') ws.cell(row=total_row, column=4, value=f'=SUM(D2:D{total_row-1})')

Number formatting

Number formatting

for row in range(2, total_row + 1): ws.cell(row=row, column=3).number_format = '$#,##0.00' ws.cell(row=row, column=4).number_format = '$#,##0.00'
wb.save('report.xlsx')
undefined
for row in range(2, total_row + 1): ws.cell(row=row, column=3).number_format = '$#,##0.00' ws.cell(row=row, column=4).number_format = '$#,##0.00'
wb.save('report.xlsx')
undefined

Read and Analyze (Python - pandas)

读取与分析(Python - pandas)

python
import pandas as pd
python
import pandas as pd

Read Excel file

Read Excel file

df = pd.read_excel('data.xlsx', sheet_name='Sheet1')
df = pd.read_excel('data.xlsx', sheet_name='Sheet1')

Analysis

Analysis

summary = df.groupby('Category').agg({ 'Sales': 'sum', 'Quantity': 'mean' }).round(2)
summary = df.groupby('Category').agg({ 'Sales': 'sum', 'Quantity': 'mean' }).round(2)

Write to Excel with formatting

Write to Excel with formatting

with pd.ExcelWriter('analysis.xlsx', engine='openpyxl') as writer: df.to_excel(writer, sheet_name='Raw Data', index=False) summary.to_excel(writer, sheet_name='Summary')
# Auto-adjust column widths
for sheet in writer.sheets.values():
    for column in sheet.columns:
        max_length = max(len(str(cell.value)) for cell in column)
        sheet.column_dimensions[column[0].column_letter].width = max_length + 2
undefined
with pd.ExcelWriter('analysis.xlsx', engine='openpyxl') as writer: df.to_excel(writer, sheet_name='Raw Data', index=False) summary.to_excel(writer, sheet_name='Summary')
# Auto-adjust column widths
for sheet in writer.sheets.values():
    for column in sheet.columns:
        max_length = max(len(str(cell.value)) for cell in column)
        sheet.column_dimensions[column[0].column_letter].width = max_length + 2
undefined

Add Charts (Python)

添加图表(Python)

python
from openpyxl.chart import BarChart, Reference

chart = BarChart()
chart.title = 'Sales by Product'
chart.x_axis.title = 'Product'
chart.y_axis.title = 'Sales'
python
from openpyxl.chart import BarChart, Reference

chart = BarChart()
chart.title = 'Sales by Product'
chart.x_axis.title = 'Product'
chart.y_axis.title = 'Sales'

Data range (assumes column D contains the series and row 1 is headers)

Data range (assumes column D contains the series and row 1 is headers)

max_row = ws.max_row data_ref = Reference(ws, min_col=4, min_row=1, max_row=max_row, max_col=4) categories = Reference(ws, min_col=1, min_row=2, max_row=max_row)
chart.add_data(data_ref, titles_from_data=True) chart.set_categories(categories) chart.shape = 4
ws.add_chart(chart, 'F2')
undefined
max_row = ws.max_row data_ref = Reference(ws, min_col=4, min_row=1, max_row=max_row, max_col=4) categories = Reference(ws, min_col=1, min_row=2, max_row=max_row)
chart.add_data(data_ref, titles_from_data=True) chart.set_categories(categories) chart.shape = 4
ws.add_chart(chart, 'F2')
undefined

Conditional Formatting

条件格式设置

python
from openpyxl.formatting.rule import ColorScaleRule, FormulaRule
from openpyxl.styles import PatternFill
python
from openpyxl.formatting.rule import ColorScaleRule, FormulaRule
from openpyxl.styles import PatternFill

Color scale (heatmap)

Color scale (heatmap)

ws.conditional_formatting.add( 'D2:D100', ColorScaleRule( start_type='min', start_color='FF0000', end_type='max', end_color='00FF00' ) )
ws.conditional_formatting.add( 'D2:D100', ColorScaleRule( start_type='min', start_color='FF0000', end_type='max', end_color='00FF00' ) )

Highlight cells above threshold

Highlight cells above threshold

red_fill = PatternFill(start_color='FFCCCC', fill_type='solid') ws.conditional_formatting.add( 'D2:D100', FormulaRule(formula=['D2>1000'], fill=red_fill) )

---
red_fill = PatternFill(start_color='FFCCCC', fill_type='solid') ws.conditional_formatting.add( 'D2:D100', FormulaRule(formula=['D2>1000'], fill=red_fill) )

---

Common Formulas Reference

常用公式参考

PurposeFormulaExample
Sum
=SUM(range)
=SUM(A1:A10)
Average
=AVERAGE(range)
=AVERAGE(B2:B100)
Count
=COUNT(range)
=COUNT(C:C)
Conditional sum
=SUMIF(range,criteria,sum_range)
=SUMIF(A:A,"Widget",B:B)
Lookup
=VLOOKUP(value,range,col,FALSE)
=VLOOKUP(A2,Data!A:C,3,FALSE)
If
=IF(condition,true,false)
=IF(B2>100,"High","Low")
Percentage
=value/total
=B2/SUM(B:B)

用途公式示例
求和
=SUM(range)
=SUM(A1:A10)
平均值
=AVERAGE(range)
=AVERAGE(B2:B100)
计数
=COUNT(range)
=COUNT(C:C)
条件求和
=SUMIF(range,criteria,sum_range)
=SUMIF(A:A,"Widget",B:B)
查找
=VLOOKUP(value,range,col,FALSE)
=VLOOKUP(A2,Data!A:C,3,FALSE)
条件判断
=IF(condition,true,false)
=IF(B2>100,"High","Low")
百分比
=value/total
=B2/SUM(B:B)

Decision Tree

决策树

text
Excel Task: [What do you need?]
    ├─ Create new spreadsheet?
    │   ├─ Simple data export → pandas to_excel()
    │   ├─ Formatted report → exceljs or openpyxl
    │   └─ With charts → openpyxl charts module
    ├─ Read/analyze existing?
    │   ├─ Data analysis → pandas read_excel()
    │   ├─ Preserve formatting → openpyxl load_workbook()
    │   └─ Fast parsing → xlsx (SheetJS)
    ├─ Modify existing?
    │   ├─ Add data → openpyxl (preserves formatting)
    │   └─ Update formulas → openpyxl
    └─ Complex features?
        ├─ Pivot tables → pandas summary tables or xlwings (native pivots)
        ├─ Data validation → openpyxl DataValidation
        └─ Macros → preserve only; use xlwings for Excel automation

text
Excel Task: [What do you need?]
    ├─ Create new spreadsheet?
    │   ├─ Simple data export → pandas to_excel()
    │   ├─ Formatted report → exceljs or openpyxl
    │   └─ With charts → openpyxl charts module
    ├─ Read/analyze existing?
    │   ├─ Data analysis → pandas read_excel()
    │   ├─ Preserve formatting → openpyxl load_workbook()
    │   └─ Fast parsing → xlsx (SheetJS)
    ├─ Modify existing?
    │   ├─ Add data → openpyxl (preserves formatting)
    │   └─ Update formulas → openpyxl
    └─ Complex features?
        ├─ Pivot tables → pandas summary tables or xlwings (native pivots)
        ├─ Data validation → openpyxl DataValidation
        └─ Macros → preserve only; use xlwings for Excel automation

Do / Avoid (Jan 2026)

建议遵循/避免事项(2026年1月)

Do

建议

  • Separate Inputs / Calculations / Outputs (tabs or clear sections).
  • Keep assumptions explicit (value + unit + source + date).
  • Add control totals and reconciliation checks for imported data.
  • 分离输入/计算/输出(使用不同工作表或清晰的分区)。
  • 明确标注假设条件(数值+单位+来源+日期)。
  • 为导入的数据添加控制总计和对账检查。

Avoid

避免

  • Hardcoded constants inside formulas without a documented assumption.
  • Hidden rows/columns that change results without documentation.
  • Sharing sheets with customer PII or secrets.
  • 在公式中使用硬编码常量且不记录假设条件。
  • 使用会影响结果但未记录的隐藏行/列。
  • 共享包含客户PII或机密信息的工作表。

What Good Looks Like

优秀实践示例

  • Structure: clear Inputs/Assumptions, Calculations, and Outputs separation (tabs or sections).
  • Integrity: no
    #REF!
    , broken named ranges, or hardcoded constants hidden in formulas.
  • Traceability: every key output ties back to labeled inputs (units + source + date).
  • Checks: control totals, reconciliations, and error flags that fail loudly.
  • Review: independent review pass using
    assets/spreadsheet-model-review-checklist.md
    .
  • 结构:清晰分离输入/假设条件、计算和输出(工作表或分区)。
  • 完整性:无
    #REF!
    错误、失效的命名范围或隐藏在公式中的硬编码常量。
  • 可追溯性:每个关键输出都能关联到带标注的输入(单位+来源+日期)。
  • 检查:设置控制总计、对账和错误标记,出现问题时及时告警。
  • 审核:使用
    assets/spreadsheet-model-review-checklist.md
    进行独立审核。

Optional: AI / Automation

可选:AI/自动化

Use only when explicitly requested and policy-compliant.
  • Generate first-pass formulas/charts; humans verify correctness and edge cases.
  • Draft documentation tabs (assumptions, glossary); do not invent source data.
仅在明确要求且符合政策时使用。
  • 生成初稿公式/图表;由人工验证正确性和边缘情况。
  • 起草文档工作表(假设条件、术语表);切勿编造源数据。

Navigation

导航

Resources
  • references/excel-formulas.md — Formula reference and patterns
  • references/excel-formatting.md — Styling, conditional formatting
  • references/excel-charts.md — Chart types and customization
  • data/sources.json — Library documentation links
Templates
  • assets/financial-report.md — Financial statement template
  • assets/data-dashboard.md — Dashboard with charts
  • assets/spreadsheet-model-review-checklist.md — Model QA checklist (assumptions, formulas, traceability)
Related Skills
  • ../document-pdf/SKILL.md — PDF generation from data
  • ../ai-ml-data-science/SKILL.md — Data analysis patterns
  • ../data-sql-optimization/SKILL.md — Database to Excel workflows
资源
  • references/excel-formulas.md — 公式参考与模式
  • references/excel-formatting.md — 样式设置、条件格式
  • references/excel-charts.md — 图表类型与自定义
  • data/sources.json — 库文档链接
模板
  • assets/financial-report.md — 财务报表模板
  • assets/data-dashboard.md — 带图表的仪表板模板
  • assets/spreadsheet-model-review-checklist.md — 模型QA检查表(假设条件、公式、可追溯性)
相关技能
  • ../document-pdf/SKILL.md — 从数据生成PDF
  • ../ai-ml-data-science/SKILL.md — 数据分析模式
  • ../data-sql-optimization/SKILL.md — 数据库转Excel工作流