antvis
diff --git a/‎.claude-plugin/marketplace.json‎
Lines changed: 9 additions & 0 deletions b/‎.claude-plugin/marketplace.json‎
Lines changed: 9 additions & 0 deletions
diff --git a/‎.env.example‎
Lines changed: 14 additions & 0 deletions b/‎.env.example‎
Lines changed: 14 additions & 0 deletions
diff --git a/‎.github/workflows/test.yml‎
Lines changed: 3 additions & 0 deletions b/‎.github/workflows/test.yml‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎.gitignore‎
Lines changed: 32 additions & 0 deletions b/‎.gitignore‎
Lines changed: 32 additions & 0 deletions
diff --git a/‎Agent.md‎
Lines changed: 142 additions & 0 deletions b/‎Agent.md‎
Lines changed: 142 additions & 0 deletions
diff --git a/‎CLAUDE.md‎
Lines changed: 1 addition & 0 deletions b/‎CLAUDE.md‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎README.md‎
Lines changed: 97 additions & 1 deletion b/‎README.md‎
Lines changed: 97 additions & 1 deletion
diff --git a/‎__tests__/info.test.ts‎
Lines changed: 26 additions & 0 deletions b/‎__tests__/info.test.ts‎
Lines changed: 26 additions & 0 deletions
diff --git a/‎__tests__/retrieve.test.ts‎
Lines changed: 39 additions & 0 deletions b/‎__tests__/retrieve.test.ts‎
Lines changed: 39 additions & 0 deletions
@@ -45,6 +45,15 @@
         "./skills/narrative-text-visualization"
       ]
     },
+    {
+      "name": "antv-g2-chart",
+      "description": "Generate G2 v5 chart code. Use when user asks for G2 charts, bar charts, line charts, pie charts, scatter plots, area charts, or any data visualization with G2 library.",
+      "source": "./",
+      "strict": false,
+      "skills": [
+        "./skills/antv-g2-chart"
+      ]
+    },
     {
       "name": "antv-s2-expert",
       "description": "S2 multi-dimensional cross-analysis table development assistant. Use when users need help with S2 pivot tables, table sheets, or any @antv/s2 related development.",
 
@@ -0,0 +1,14 @@
+# AI Provider API Keys
+# Playground Provider Path: playground/src/libs/provider.ts
+
+# DeepSeek API Key
+DEEPSEEK_API_KEY=your-deepseek-api-key-here
+# DeepSeek API Endpoint
+DEEPSEEK_API_ENDPOINT=https://api.deepseek.com
+# DeepSeek API Path
+DEEPSEEK_API_PATH=/v1/chat/completions
+# DeepSeek Model Name
+DEEPSEEK_MODEL=model-name
+
+# VL Model Name（Optional）
+VL_MODEL=model-name 
@@ -24,5 +24,8 @@ jobs:
       - name: Install dependencies
         run: npm install
 
+      - name: Buidl project
+        run: npm run build
+
       - name: Run tests
         run: npm test
@@ -42,3 +42,35 @@ yarn-error.log*
 # OS
 .DS_Store
 Thumbs.db
+
+# env
+.env
+
+# Eval results (local runs, not for review)
+# eval/result/
+logs
+
+# Validator state directory
+eval/temp/
+
+# harness
+harness/memory.json
+
+# lock files
+pnpm-lock.yaml
+
+# skills index
+src/index/
+
+# Playground (Next.js)
+playground/.next/
+playground/node_modules/
+playground/.env.local
+playground/out/
+
+
+# TypeScript build cache
+*.tsbuildinfo
+
+# AI
+settings.local.json
@@ -0,0 +1,142 @@
+# Agent.md - AntV Chart Visualization Skills
+
+## Overview
+
+This project is a skill-based system for generating chart visualization code using AntV libraries (G2, G6, S2, etc.). It provides AI agents with structured knowledge about chart types, best practices, and API usage, enabling them to generate correct chart code from natural language queries.
+
+## Core Workflow
+
+```
+                                ┌─────────────────────────┐
+                                │   Document + Code       │
+                                └───────────┬─────────────┘
+                                            │
+                                            v
+                               ┌────────────────────────┐
+                          ┌───>│        Skills          │<────┐
+                          │    └───────────┬────────────┘     │
+                          │                │                  │
+                          │                v                  │
+                          │    ┌────────────────────────┐     │
+                          │    │       CLI Tool         │     │
+                          │    │  (BM25 Retrieve/List)  │     │
+                          │    └───────────┬────────────┘     │
+                          │                │                  │
+                          │                v                  │
+                          │    ┌────────────────────────┐     │
+                          │    │     Eval + Harness     │     │
+                          │    │  (evaluate & optimize) │─────┘
+                          │    └───────────┬────────────┘
+                          │                │
+                          │                v
+                          │    ┌────────────────────────┐
+                          └────│      Playground        │
+                               │  (interactive preview) │
+                               └────────────────────────┘
+```
+
+Eval + Harness 通过自动化评测发现问题，再由 LLM 优化 Skill 文档，形成闭环持续提升 Skill 质量。
+
+### 1. Skill Authoring (`skills/`)
+
+Skills are markdown files with YAML frontmatter, organized by library. Each skill documents a chart type or visualization pattern with metadata (category, tags, difficulty, use cases) and content (best practices, API usage, code examples).
+
+```
+skills/
+├── antv-g2-chart/       # G2 chart skills + reference docs
+├── antv-s2-expert/      # S2 pivot table skills
+├── chart-visualization/  # Generic chart visualization via REST API
+├── icon-retrieval/       # Icon retrieval skill
+├── infographic-creator/  # Infographic creation
+└── narrative-text-visualization/
+```
+
+Skills are the **single source of truth** for chart generation knowledge.
+
+### 2. CLI Tool (`src/`)
+
+The build script (`src/scripts/build.ts`) parses all skill markdown files and generates JSON index files (`src/index/*.index.json`). The CLI (`antv` command) provides three commands:
+
+- `antv retrieve <query>` - BM25 full-text search over skills
+- `antv list` - List/filter available skills
+- `antv info <library>` - Show library metadata
+
+The retrieval engine (`src/core/bm25.ts`) implements BM25 with Chinese/English tokenization, synonym expansion, and chart-type boosting.
+
+Public API (`src/api.ts`) exports `retrieve()` and `info()` for programmatic use.
+
+### 3. Evaluation (`eval/`)
+
+Automated evaluation framework that measures skill quality across retrieval strategies:
+
+- **tool-call**: LLM uses tools to load skills on demand (multi-turn agent)
+- **bm25**: Pre-retrieve top-K skills via BM25, inject into prompt (single-turn)
+- **context7**: Fetch official docs via REST API (single-turn)
+
+Key files:
+- `eval/data/eval-g2-dataset-174.json` - 174 labeled test cases
+- `eval/eval-cli/index.js` - Main eval runner
+- `eval/eval-recall.js` - BM25 retrieval recall measurement
+
+### 4. Harness (`harness/`)
+
+Iterative optimization loop that automatically improves skills based on eval results:
+
+```
+Eval --> Render Test --> Error Analysis --> Optimize Skills --> Rebuild Index --> Repeat
+```
+
+The controller (`harness/controller.js`) orchestrates five agents:
+- **EvalAgent** - Run LLM eval on dataset samples
+- **RenderAgent** - Execute generated code in headless browser
+- **AnalyzeAgent** - Classify errors and attribute to specific skills
+- **OptimizeAgent** - LLM rewrites skill docs to fix errors
+- **IndexAgent** - Rebuild BM25 search index
+
+Iterates until MAX_PASSES consecutive clean passes are achieved.
+
+### 5. Playground (`playground/`)
+
+Next.js web app for interactive chart generation. Dual-panel UI with chat interface, code editor (Monaco), and real-time chart preview.
+
+Two retrieval modes:
+- **Skill mode** - Agent calls `load_skill` / `read_file` tools
+- **CLI mode** - Pre-injected BM25 results in system prompt
+
+## Project Structure
+
+```
+.
+├── src/                  # Core library: CLI, API, BM25 retriever, build scripts
+│   ├── index.ts          # CLI entry point (Commander.js)
+│   ├── api.ts            # Public Node.js API
+│   ├── commands/         # CLI commands (retrieve, list, info)
+│   ├── core/             # BM25 engine, types
+│   ├── scripts/          # Build script (markdown -> JSON index)
+│   └── index/            # Generated JSON index files
+├── skills/               # Skill definitions (markdown + YAML frontmatter)
+├── eval/                 # Evaluation framework and test datasets
+├── harness/              # Automated skill optimization loop
+├── playground/           # Next.js interactive playground
+├── __tests__/            # Vitest unit tests
+└── package.json          # @antv/chart-visualization-skills
+```
+
+## Key Commands
+
+```bash
+# Build: parse skills -> generate index -> compile TypeScript
+pnpm build
+
+# Test
+pnpm test
+
+# Eval: run evaluation on dataset
+node eval/eval-cli/index.js --retrieval=bm25 --dataset=eval-g2-dataset-174
+
+# Harness: iterative optimization
+node harness/controller.js --library=g2 --sample=10 --retrieval=bm25
+
+# Playground: start dev server
+cd playground && pnpm dev
+```
@@ -0,0 +1 @@
+See [Agent.md](./Agent.md) for project architecture and structure.
@@ -50,9 +50,105 @@ npx skills add antvis/chart-visualization-skills
 
 `AntV S2 Expert` helps users develop with the S2 multi-dimensional cross-analysis table engine. It provides comprehensive guidance on `@antv/s2` core engine, `@antv/s2-react` and `@antv/s2-vue` framework bindings, `@antv/s2-react-components` advanced analysis components, and `@antv/s2-ssr` server-side rendering. Covers pivot tables, table sheets, custom cells, theming, events, interactions, sorting, totals, tooltips, frozen rows/columns, icons, pagination, and more.
 
+- 📈 **antv-g2-chart**: G2 v5 chart code generator. Use when users need to generate G2 charts — bar charts, line charts, pie charts, scatter plots, area charts, heatmaps, and any statistical data visualization with the G2 library.
+
+`AntV G2 Chart` generates accurate, runnable G2 v5 code following Spec Mode best practices. It covers 30+ chart types (interval, line, area, point, rect, cell, treemap, sankey, chord, wordCloud, gauge, and more), data transforms (stackY, dodgeX, binX, fold, etc.), coordinate systems (cartesian, polar, theta, radial), scales, interactions (brush, slider, legend filter), components (axis, legend, tooltip, annotation), and multi-view compositions. Built-in guard rails prevent common v4→v5 migration pitfalls such as using deprecated chain APIs, invalid palette names, or referencing `d3` in user code.
+
+**Evaluation Results**
+
+Harness Engineering approach has been rigorously tested against 174 chart generation test cases, demonstrating significant improvements over baseline methods:
+
+| Model | Success Rate | Improvement |
+| :--- | :--- | :--- |
+| qwen3-coder-480b-a35b-instruct | **98.2%** | +18.2% |
+| Kimi-K2.5 | **97.7%** | +17.7% |
+| GLM-5.1 | **93.6%** | +13.6% |
+| DeepSeek-V3.2 | **87.3%** | +7.3% |
+| Context7 Baseline | 80% | baseline |
+
+The results show that Harness Engineering enables LLMs to achieve near-production-ready accuracy (up to 98.2%), significantly outperforming the Context7 baseline approach.
+
 > [!TIP]
 > More skills are coming soon.
 
+## CLI Usage
+
+We also provide a CLI tool named `antv` for easy usage in your terminal, Install globally:
+
+```bash
+npm install -g chart-visualization-skills
+```
+
+**Retrieve or list skills by query**:
+
+```bash
+# Retrieve skills by query
+antv retrieve "bar chart" --library g2 --topk 10 --content
+
+# List all available skills
+antv list --library g2 --category core
+
+# Show skill info
+antv info --library g2
+```
+
+**Usage for the command**:
+
+```
+Usage: antv [options] [command]
+
+CLI tool for AntV chart visualization skills retrieval
+
+Options:
+  -V, --version               output the version number
+  -h, --help                  display help for command
+
+Commands:
+  retrieve [options] <query>  Search for skills matching a query
+  list [options]              List all available skills
+  info [options]              Show skill info from SKILL.md
+  help [command]              display help for command
+```
+
+## API Usage
+
+```typescript
+import { retrieve } from 'chart-visualization-skills';
+
+const skills = retrieve('bar chart', 'g2', 5);
+// with content body: retrieve('bar chart', 'g2', 5, true)
+```
+
+```typescript
+retrieve(query: string, library?: string, topk?: number, content?: boolean)
+```
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `query` | `string` | — | Search query |
+| `library` | `string` | `'g2'` | Library filter (`g2` or `g6`) |
+| `topk` | `number` | `7` | Number of results |
+| `content` | `boolean` | `false` | Whether to include markdown content |
+
+> Notes:
+> - Default retrieval returns lightweight result objects without the `content` field.
+> - `content = true` returns markdown content body (frontmatter metadata is excluded).
+
+```typescript
+import { info } from 'chart-visualization-skills';
+
+const skillInfo = info('g2');
+// => { name: 'antv-g2-chart', description: '...', content: '...' }
+```
+
+```typescript
+info(library?: string): SkillInfo | undefined
+```
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `library` | `string` | `'g2'` | Library to get info for (`g2` or `g6`) |
+
 ## License
 
-MIT License - see the [LICENSE](LICENSE) file for details.
+MIT License - see the [LICENSE](LICENSE) file for details.
@@ -0,0 +1,26 @@
+import { describe, it, expect } from 'vitest';
+import { info } from '../src/api';
+
+describe('info API', () => {
+  it('should return skill info for default library', () => {
+    const result = info();
+    expect(result).toBeDefined();
+    expect(result!.name).toBe('antv-g2-chart');
+    expect(result!.description.length).toBeGreaterThan(0);
+    expect(result!.content.length).toBeGreaterThan(0);
+  });
+
+  it('should return skill info for g2 library', () => {
+    const result = info('g2');
+    expect(result).toBeDefined();
+    expect(result).toHaveProperty('name');
+    expect(result).toHaveProperty('description');
+    expect(result).toHaveProperty('content');
+  });
+
+  it('should return undefined for library without SKILL.md', () => {
+    const result = info('g6');
+    // g6 may or may not have a SKILL.md
+    expect(result === undefined || typeof result.name === 'string').toBe(true);
+  });
+});
@@ -0,0 +1,39 @@
+import { describe, it, expect } from 'vitest';
+import { retrieve } from '../src/api';
+
+describe('retrieve API', () => {
+  it('should retrieve skills with default parameters', () => {
+    const results = retrieve('折线图');
+    expect(results.length).toBeGreaterThan(0);
+    expect(results.length).toBeLessThanOrEqual(7);
+    expect(results[0]).toHaveProperty('id');
+    expect(results[0]).toHaveProperty('title');
+    expect(results[0].content).toBeUndefined();
+  });
+
+  it('should respect topk parameter', () => {
+    const results = retrieve('bar chart', 'g2', 3);
+    expect(results.length).toBeGreaterThan(0);
+    expect(results.length).toBeLessThanOrEqual(3);
+  });
+
+  it('should support g6 library parameter', () => {
+    const results = retrieve('graph layout', 'g6');
+    expect(Array.isArray(results)).toBe(true);
+  });
+
+  it('should handle mixed Chinese/English query', () => {
+    const results = retrieve('饼图 tooltip', 'g2', 5);
+    expect(results.length).toBeGreaterThan(0);
+    expect(results.length).toBeLessThanOrEqual(5);
+  });
+
+  it('should load markdown content on demand', () => {
+    const results = retrieve('折线图', 'g2', 1, true);
+    expect(results.length).toBeGreaterThan(0);
+    expect(typeof results[0].content).toBe('string');
+    expect((results[0].content || '').length).toBeGreaterThan(0);
+    // content should be body only, without frontmatter
+    expect(results[0].content).not.toMatch(/^---\n/);
+  });
+});
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+See [Agent.md](./Agent.md) for project architecture and structure.`