https://github.com/seacen/data-analyst-sz
A trained senior data analyst as an on-call skill — runs a professional 9-step framework on any structured data, every number traceable. 把训练有素的资深数据分析师做成随叫随到的 skill:专业 9-step 分析框架,任意结构化数据都能跑,每个数字可追溯。
https://github.com/seacen/data-analyst-sz
agent-skills ai-agents anti-hallucination claude-code codex data-analysis data-analyst data-visualization domain-pack llm pandas skills
Last synced: 11 days ago
JSON representation
A trained senior data analyst as an on-call skill — runs a professional 9-step framework on any structured data, every number traceable. 把训练有素的资深数据分析师做成随叫随到的 skill:专业 9-step 分析框架,任意结构化数据都能跑,每个数字可追溯。
- Host: GitHub
- URL: https://github.com/seacen/data-analyst-sz
- Owner: seacen
- License: other
- Created: 2026-07-05T08:23:50.000Z (20 days ago)
- Default Branch: main
- Last Pushed: 2026-07-05T10:13:18.000Z (20 days ago)
- Last Synced: 2026-07-05T11:13:57.408Z (20 days ago)
- Topics: agent-skills, ai-agents, anti-hallucination, claude-code, codex, data-analysis, data-analyst, data-visualization, domain-pack, llm, pandas, skills
- Size: 422 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.en.md
- License: LICENSE
- Notice: NOTICE
Awesome Lists containing this project
README
# Data Analyst SZ
> **A trained senior data analyst, packaged as an on-call skill.** Give it any structured data and a business question; it runs a fixed professional method (the **9-step framework**) end to end, and delivers a report-ready deck + report — every number computed for real and fully traceable.
**🌐 Language:** [**中文**](README.md) · **English (this page)**
[](LICENSE)
---
## Why it's professional: a trained analysis method
The core is the **9-step framework** — a senior analyst's way of working, fixed into an executable discipline instead of letting the model improvise over the data. Every analysis follows the same professional sequence:
**Understand the data → frame the business question into an issue tree → hypothesize → verify each hypothesis with real computation → decompose the drivers (which segment or step moved it, who's up and who's down) → synthesize a report-ready deck + report → take follow-ups.**
It won't stop at "a metric is down 6%" and call it done — it drills to the root cause (which segment or step is moving, who's up and who's down), then answers the question that matters most: **"so what? what does it mean?"** Every insight names the object, gives the number, and points to the implication and the next move. That's the difference between a senior analyst and a plain report — and it's what this method delivers every time.
## What you get: a polished, report-ready deck
When the analysis finishes, it produces a **self-contained HTML deck + companion report** by default (a 1:1 mirror, slide by slide) — no layout work on your side:
- **Professionally laid out, ready to present** — every slide carries a **so-what headline** (object + number + conclusion), so the point lands at a glance.
- **Rich charts:** bars, matrix heatmaps, bullet charts, scatter, waterfall bridges… each finding is routed to the chart that fits it, not the same bar chart every time.
- **Opinionated and decision-ready:** each slide spells out where the opportunity is, where the risk is, and what to do next — not just a pile of charts.
- Every number on every chart traces back to a `verdict_id` and the source data.
## Numbers you can trust: anti-hallucination, fully traceable
The LLM only narrates — it never computes numbers or substitutes intuition for business rules:
- Every number is produced by **pandas** the agent writes and runs, saved to `verdicts.json`; every claim in the report cites a `verdict_id` you can trace back to the source data.
- Rule-engine conclusions must carry a `rule_source` (anchored to your rule tables); when the rules aren't enough, it outputs "pending business rule" and never fabricates.
## Universality: no requirement on the source data — feed it anything
By design it makes no assumptions about the data or the domain. That universality shows up in three layers:
1. **Generalization — both layers generalize.** The universal 9-step method fits any analysis; the domain-pack layer lets the same engine understand a new field just by swapping the pack. Change the question, change the columns — it profiles the data at runtime, abstracts field roles, and still runs.
2. **Tool universality — the builder is universal too.** `domain-pack-builder` is itself a generic factory: hand it **any** field's material and it produces that field's pack. You aren't limited to pre-built domains — you can make this analysis an expert in **your own** field.
3. **Data compatibility — no dependency on the raw data's shape.** Excel / CSV / Parquet / DataFrame, any schema. It reads the data profile at runtime and maps columns to abstract roles — nothing about any single dataset's structure is hardcoded.
## The real value: distill analysis capability into an asset
Its core idea is to **distill your team's analysis method, reasoning, and business understanding into one reusable, pluggable asset**. What normally lives only in one senior analyst's head, once encoded, becomes available on demand to everyone. Build a pack for a new field once, and from then on everyone gets that expert's caliber of analysis.
---
## The two skills
One plugin bundling two skills that work together:
| Skill | Role | In one line |
|---|---|---|
| **`data-analysis`** | Consumer | Upload any structured data + ask an analytical question; it runs the **9-step framework** end to end, delivers a report-ready **deck + report** by default, and takes follow-ups. |
| **`domain-pack-builder`** | Builder | A generic factory for building **any** domain pack: it studies your field's raw material (training decks / sample analyses / data) like a researcher → synthesizes an *Understanding Handbook* → derives that field's domain pack for `data-analysis` to load. |
**Architecture:** the methodology is **generic** (the universal `references/` layer carries zero domain knowledge); domain knowledge lives in **pluggable domain packs** (`domains//`). See [`docs/DESIGN.md`](docs/DESIGN.md) for the full design.
---
## Install
Pick any one (the same repo serves all three). You get two skills: `data-analysis` and `domain-pack-builder`.
### 1) npx (most universal, cross-agent, via [vercel-labs/skills](https://github.com/vercel-labs/skills))
```
npx skills add seacen/data-analyst-sz --all
```
`--all` installs both skills to every compatible agent, no prompts. To choose the agent yourself, use `--skill '*'` (all skills, then pick the agent); add `-g` to install globally.
### 2) Claude Code (plugin — installs both at once)
```
/plugin marketplace add seacen/data-analyst-sz
/plugin install data-analyst-sz@data-analyst-sz
```
### 3) Codex (OpenAI Codex CLI)
Use the built-in `skill-installer` inside a Codex session:
```
$skill-installer install https://github.com/seacen/data-analyst-sz/tree/main/skills/data-analysis
$skill-installer install https://github.com/seacen/data-analyst-sz/tree/main/skills/domain-pack-builder
```
Restart Codex afterwards to pick up the new skills.
> `SKILL.md` is the cross-vendor [Agent Skills open standard](https://agentskills.io) — Claude Code / Codex / Cursor / Copilot read it directly, no conversion needed.
---
## Quick start
1. **Have a domain pack ready.** This repo ships a **synthetic e-commerce example** pack (`skills/data-analysis/domains/ecommerce/`) — install and try it. For your own field, see below.
2. **Give data + ask a question.** Hand your structured data to `data-analysis` and ask a business question, for example:
> "Analyze GMV and growth by category and channel — where is it growing, where are the opportunities?"
3. **It automatically** routes to the matching domain → runs the full 9-step → delivers `outputs/insight_deck.html` + `outputs/insight_report.md`, every number traceable.
> ⚠️ Runtime artifacts (`outputs/`, verdict JSON, generated scripts) are anchored to your working directory — never written into the skill's install directory.
---
## Build your own domain pack
A new field needs no skill edits — use `domain-pack-builder`:
1. Hand it your field's raw material (training decks / a sample analysis to replicate / real data / SME interviews).
2. It **reads visually page by page** → synthesizes an *Understanding Handbook* → **derives** the domain pack (framework / glossary / computation-reference / data-spec / triggers / insight-extensions / business-rules…), flagging anything uncertain with `⚠️待确认` (to-confirm).
3. The business edits `⚠️待确认` into final values in Typora/Obsidian.
4. Drop the resulting pack into `skills/data-analysis/domains//` and `data-analysis` can route to and analyze it.
`domain-pack-builder` itself carries **zero domain knowledge**; domain specifics come only from your input material and land only in the produced pack.
---
## Repository layout
```
data-analyst-sz/
├── skills/
│ ├── data-analysis/ # Consumer skill: 9-step framework + universal-layer references
│ │ ├── SKILL.md
│ │ ├── references/ # Universal layer (domain-neutral): 9-step / anti-hallucination / protocol / deck templates…
│ │ └── domains/
│ │ └── ecommerce/ # ★ Bundled synthetic e-commerce example domain pack
│ └── domain-pack-builder/ # Builder skill: study material → handbook → derive pack
│ ├── SKILL.md
│ └── references/
├── docs/DESIGN.md # Design document for both skills
├── .claude-plugin/ # Claude Code plugin / marketplace manifests
├── LICENSE # Apache-2.0
└── README.md
```
---
## Notes
- This suite's methodology was refined on a real enterprise analytics project; that project's domain pack contains company-sensitive information and is **not included in this public repo**. The `domains/` folder ships a **synthetic e-commerce example** (entirely fictional, non-sensitive) to demonstrate the capability and let you run it out of the box.
- Both skills are in the [Agent Skills open standard](https://agentskills.io) format — reusable and portable.
## License
[Functional Source License 1.1 (FSL-1.1-ALv2)](LICENSE) — © 2026 Seacen Zhao . Free for any Permitted Purpose (**including internal and work use**); reselling, bundling into a paid product, or offering the software itself as a hosted/SaaS service requires a separate license from the copyright holder. Each version converts to Apache-2.0 two years after its release.