Initial commit
This commit is contained in:
Z User
230
skills/xlsx/SKILL.md
Executable file
230
skills/xlsx/SKILL.md
Executable file
@@ -0,0 +1,230 @@
|
||||
---
|
||||
name: xlsx
|
||||
metadata:
|
||||
author: Z.AI
|
||||
version: "1.0"
|
||||
description: "Use this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .csv, or .tsv file; create a new spreadsheet from scratch or from other data sources; analyze data and output results as an Excel file with charts; convert between tabular file formats (CSV/JSON/PDF → XLSX or vice versa); clean, merge, pivot, or transform tabular data. Trigger especially when the user references a spreadsheet file by name or path, says 'make a table/report/model', mentions Excel/CSV/数据分析/报表/汇总, or wants data visualization inside a spreadsheet."
|
||||
license: Proprietary. LICENSE.txt has complete terms
|
||||
---
|
||||
|
||||
# XLSX — Scene-Driven Spreadsheet Workbench
|
||||
|
||||
## Quick Setup
|
||||
|
||||
```bash
|
||||
bash "$XLSX_SKILL_DIR/setup.sh" # Interactive environment check + install
|
||||
```
|
||||
## Pre-Flight: Intent Gate
|
||||
|
||||
Before touching any code, confirm the user actually needs a spreadsheet:
|
||||
|
||||
- Report / analysis summary (述职, 调研报告) → **docx skill**
|
||||
- Presentation (汇报, 演示, pitch deck) → **pptx skill**
|
||||
- Formal print document (合同, 证书, "PDF") → **pdf skill**
|
||||
- Charts only, no data table needed → **charts skill**
|
||||
- User explicitly says a format → respect it
|
||||
|
||||
If confirmed xlsx → proceed to Scene Router below.
|
||||
|
||||
**Request Decomposition** (do this every time):
|
||||
- **Explicit needs**: sheets, columns, formulas, metrics the user stated
|
||||
- **Implicit needs**: business context, downstream use (filter? sort? input?)
|
||||
- **Multi-part requests**: generate ALL parts — never silently drop a component
|
||||
|
||||
**Multi-Intent Detection** — some requests combine multiple scenes:
|
||||
|
||||
```
|
||||
"Create a financial model with charts and export a PDF summary"
|
||||
→ scenes/finance.md + engines/chart.md + (hand off PDF to pdf skill)
|
||||
|
||||
"Analyze this CSV, build a dashboard, and make it look professional"
|
||||
→ scenes/analyze.md + engines/chart.md + engines/design.md
|
||||
|
||||
"Edit this budget file, add a new quarter column, and create a pivot"
|
||||
→ scenes/edit.md + quality/pipeline.md (pivot command)
|
||||
|
||||
"Convert these 5 CSVs into one xlsx with a summary sheet"
|
||||
→ scenes/convert.md + scenes/create.md (for summary)
|
||||
```
|
||||
|
||||
When multiple intents detected, load all matching files and execute in logical order: data preparation → analysis → visualization → styling → QA.
|
||||
|
||||
---
|
||||
|
||||
## Complexity Gate (evaluate BEFORE Scene Router)
|
||||
|
||||
Determine task complexity to control file loading depth:
|
||||
|
||||
```
|
||||
User Request
|
||||
│
|
||||
├─ LITE (single aggregation, simple chart, direct conversion, QA-only)
|
||||
│ → Load: SKILL.md + ONE scene file (lean version)
|
||||
│ → Skip: engine files (use built-in knowledge for basic styles)
|
||||
│ → QA: audit + validate only
|
||||
│ → Target: ≤ 400 lines total context
|
||||
│
|
||||
└─ FULL (multi-dimensional analysis, financial model, dashboard, KANO, etc.)
|
||||
→ Load: SKILL.md + scene + engines (chart.md / design.md) as needed
|
||||
→ For code patterns: load recipes/templates files ON DEMAND (not upfront)
|
||||
→ QA: full pipeline (recalc → audit → scan → chart-verify → validate)
|
||||
→ Target: load recipes/templates only when stuck on implementation
|
||||
```
|
||||
|
||||
**LITE triggers**: single groupby, one chart, format conversion, inspect/audit/validate, simple pivot
|
||||
**FULL triggers**: correlation matrix, multi-sheet dashboard, statistical analysis, financial model, KANO/funnel/cohort
|
||||
|
||||
---
|
||||
|
||||
## Scene Router
|
||||
|
||||
```
|
||||
User Request
|
||||
│
|
||||
├─ Involves an existing file?
|
||||
│ ├─ Yes → Modify content or structure?
|
||||
│ │ ├─ Yes ──────────────────── → scenes/edit.md
|
||||
│ │ └─ No (read/analyze only) ─ → scenes/analyze.md
|
||||
│ │
|
||||
│ └─ Format conversion (CSV↔XLSX, JSON, PDF tables)?
|
||||
│ └─ Yes ────────────────────────── → scenes/convert.md
|
||||
│
|
||||
├─ Create from scratch?
|
||||
│ ├─ Financial / budget / forecast / cost tracking?
|
||||
│ │ ├─ Complex (DCF / LBO / three-statement linkage (三表联动) / sensitivity / IB model)?
|
||||
│ │ │ └─ Yes ─────────────────────── → scenes/finance.md
|
||||
│ │ └─ Simple (budget table (预算表) / expense report (费用报表) / revenue vs cost (收支对比) / project cost (项目成本) / personal finance (个人记账))?
|
||||
│ │ └─ Yes ─────────────────────── → scenes/finance_lite.md
|
||||
│ └─ General table / report / template
|
||||
│ └─ ──────────────────────────── → scenes/create.md
|
||||
│
|
||||
├─ Batch processing / large files / protection / validation?
|
||||
│ └─ Yes ───────────────────────────── → scenes/advanced.md
|
||||
│
|
||||
├─ VBA / macros / automation inside Excel?
|
||||
│ └─ Yes ───────────────────────────── → scenes/vba.md + engines/vba-templates.md
|
||||
│
|
||||
├─ Needs charts or data visualization?
|
||||
│ └─ Yes ───────────── append ────────→ engines/chart.md
|
||||
│
|
||||
└─ Needs styling / design system?
|
||||
└─ Yes ───────────── append ────────→ engines/design.md
|
||||
```
|
||||
|
||||
**Mixed requests**: load all matching files. Engine files always **append** to a scene.
|
||||
|
||||
**Finance detection**:
|
||||
- **finance.md** (complex): DCF, LBO, P&L, 利润表, 资产负债, valuation, 估值, IRR, 三表联动, sensitivity, scenario
|
||||
- **finance_lite.md** (simple): 预算, budget, 费用, expense, 收支, 记账, 项目成本, cost tracking, 报销, ROI
|
||||
|
||||
**VBA detection**: 宏, macro, VBA, 自动化, automation, .xlsm, 按钮, button, auto-run, 批量处理脚本
|
||||
|
||||
---
|
||||
|
||||
## Design Principles
|
||||
|
||||
### 1. Live Formula Guarantee
|
||||
Every derived value SHOULD be an Excel formula so the spreadsheet stays dynamic.
|
||||
|
||||
**Exception — Programmatic Verification**: When the output file will be verified by Python (not opened in Excel), TOTAL/SUM rows should write **computed values** instead of formulas, because openpyxl cannot evaluate formulas and `data_only=True` returns `None` for newly-written formulas. Optionally add the formula as a cell comment for reference.
|
||||
|
||||
### 2. Zero Error Tolerance
|
||||
Deliverables must have zero formula errors. All divisions wrapped with `IFERROR` or `IF(denom=0,...)`. Absolute references (`$C$42`) for shared denominators.
|
||||
|
||||
### 3. Compatibility First
|
||||
No dynamic array functions (`FILTER`, `UNIQUE`, `XLOOKUP`, `SORT`, `SORTBY`, `XMATCH`, `SEQUENCE`, `LET`, `LAMBDA`, `RANDARRAY`). No implicit array formulas — use `SUMPRODUCT` alternatives.
|
||||
|
||||
### 4. Preserve & Match
|
||||
When editing existing files: study and exactly match format, style, conventions. Existing patterns always override defaults. Text starting with `=` must be prefixed with `'`.
|
||||
|
||||
### 5. Language Mirror
|
||||
Output language (sheet names, headers, labels) matches user's input language.
|
||||
|
||||
### 6. Data Consistency Over Instructions
|
||||
When user instructions conflict with the actual data patterns in the existing file:
|
||||
- **First priority**: match the existing data pattern (e.g., if existing data uses `0` for empty, don't switch to `-`)
|
||||
- **Second priority**: follow user instructions literally
|
||||
- Always flag the conflict to the user
|
||||
|
||||
Example: User says "show hyphen for zero" but existing data and answer key use numeric `0` → Use `0` and notify user of the discrepancy.
|
||||
|
||||
---
|
||||
|
||||
## Toolchain
|
||||
|
||||
### Script Path Setup (MANDATORY before any script call)
|
||||
|
||||
All CLI tools live relative to this skill's directory. Before calling any script, resolve the absolute path once:
|
||||
|
||||
```bash
|
||||
XLSX_SKILL_DIR="<skill_directory>" # ← parent directory of this SKILL.md
|
||||
|
||||
# Then all commands use absolute paths:
|
||||
python3 "$XLSX_SKILL_DIR/xlsx.py" inspect data.xlsx --pretty
|
||||
python3 "$XLSX_SKILL_DIR/xlsx.py" pivot data.xlsx output.xlsx --rows Region --values Revenue
|
||||
python3 "$XLSX_SKILL_DIR/xlsx.py" validate output.xlsx
|
||||
```
|
||||
|
||||
**For Python imports** (when generation code needs to import skill modules):
|
||||
|
||||
```python
|
||||
import sys, os
|
||||
XLSX_SKILL_DIR = "<skill_directory>"
|
||||
for sub in [XLSX_SKILL_DIR, os.path.join(XLSX_SKILL_DIR, "templates")]:
|
||||
if sub not in sys.path:
|
||||
sys.path.insert(0, sub)
|
||||
```
|
||||
|
||||
**⚠️ NEVER use bare `python3 xlsx.py ...`** — it only works if cwd happens to be the skill directory. Always use the absolute path.
|
||||
|
||||
### Tool Reference
|
||||
|
||||
| Tool | Use |
|
||||
|------|-----|
|
||||
| **openpyxl** | Formulas, formatting, charts, cell-level control |
|
||||
| **pandas** | Data analysis, bulk operations, CSV/TSV |
|
||||
| `load_workbook(read_only=True)` | Large file reads |
|
||||
| `Workbook(write_only=True)` | Large file writes |
|
||||
| **templates/base.py** | Design tokens, font resolution, style factories, utilities (single source of truth) |
|
||||
| **xlsx.py** | QA commands (see `quality/pipeline.md`) |
|
||||
|
||||
Workbook metadata: `wb.properties.creator = "Z.ai"`
|
||||
|
||||
> **All code must import from `templates/base.py`** for colors, fonts, and style helpers. Never hardcode hex values or font names.
|
||||
|
||||
---
|
||||
|
||||
## Quality Gate
|
||||
|
||||
Every deliverable must pass the full integrity pipeline before delivery.
|
||||
|
||||
→ **Load `quality/pipeline.md` for the role-based integrity workflow.**
|
||||
|
||||
Quick reference:
|
||||
```
|
||||
Blueprint → Build & Self-check (per-sheet) → Inspect → Pivot (if needed) → Release
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Capability Matrix
|
||||
|
||||
| Capability | Supported | Scene/Engine |
|
||||
|-----------|-----------|-------------|
|
||||
| Create from scratch | ✅ | scenes/create |
|
||||
| Edit existing file | ✅ | scenes/edit |
|
||||
| Data analysis & EDA | ✅ | scenes/analyze |
|
||||
| Format conversion | ✅ | scenes/convert |
|
||||
| Financial models (DCF/LBO/P&L) | ✅ | scenes/finance |
|
||||
| Simple budgets & expenses | ✅ | scenes/finance_lite |
|
||||
| VBA macros & automation | ✅ | scenes/vba + engines/vba-templates |
|
||||
| Batch processing | ✅ | scenes/advanced |
|
||||
| Embedded charts | ✅ | engines/chart |
|
||||
| Smart chart recommendation | ✅ | engines/chart |
|
||||
| Design system & styling | ✅ | engines/design |
|
||||
| PivotTable creation | ✅ | quality/pipeline (pivot cmd) |
|
||||
| Formula validation | ✅ | quality/pipeline |
|
||||
| Structural validation | ✅ | quality/pipeline |
|
||||
| Data provenance tracking | ✅ | scenes/analyze |
|
||||
| Large file handling | ✅ | scenes/advanced |
|
||||
| Data protection & locking | ✅ | scenes/advanced |
|
||||
Reference in New Issue
Block a user