feat(skill): delegate skill install to vercel-labs/skills ecosystem

.github/workflows/skill-format-check.yml

@@ -5,16 +5,12 @@ on:
       - "skills/**"
       - "scripts/skill-format-check/**"
       - "scripts/skill-format-check.sh"
-      - "scripts/install-skills.sh"
-      - "scripts/install-skills-test.sh"
       - ".github/workflows/skill-format-check.yml"
   pull_request:
     paths:
       - "skills/**"
       - "scripts/skill-format-check/**"
       - "scripts/skill-format-check.sh"
-      - "scripts/install-skills.sh"
-      - "scripts/install-skills-test.sh"
       - ".github/workflows/skill-format-check.yml"
 
 jobs:
@@ -28,6 +24,3 @@ jobs:
 
       - name: Self-test (good/bad fixtures)
         run: ./scripts/skill-format-check/test.sh
-
-      - name: Installer tests (7 agents)
-        run: ./scripts/install-skills-test.sh

.well-known/agent-skills/index.json

@@ -0,0 +1,19 @@
+{
+  "skills": [
+    {
+      "name": "mysql-shared",
+      "description": "mysql-cli shared rules: config & datasource, global flags, output formats, error recovery, safety model, stable exit codes. Required by mysql-query and mysql-schema; install all three together.",
+      "path": "skills/mysql-shared/SKILL.md"
+    },
+    {
+      "name": "mysql-query",
+      "description": "Run SQL with mysql-cli: SELECT, DML (INSERT/UPDATE/DELETE), DDL, multi-statement transactions. Read-only by default, JSON output, stable exit codes, tiered write gates.",
+      "path": "skills/mysql-query/SKILL.md"
+    },
+    {
+      "name": "mysql-schema",
+      "description": "Explore MySQL schema with mysql-cli: tables, databases, sample, read, analyze. Read-only discovery.",
+      "path": "skills/mysql-schema/SKILL.md"
+    }
+  ]
+}

AGENTS.md

@@ -30,14 +30,13 @@ RUN_INTEGRATION=1 go test -tags=integration ./internal/integration/ -v
 包严格单向依赖，`result` 是无依赖底层，避免循环引用：
 
 ```
-cmd/mysql-cli/main  ->  cli（cobra 装配 + 退出码映射 + skill 子命令）
+cmd/mysql-cli/main  ->  cli（cobra 装配 + 退出码映射 + config 子命令）
                           ↓
         config ─-> conn ─-> query ─-> result
           │        │       └─-> safety（无依赖，纯逻辑）
           │        └─-> schema ─-> result/safety
           └─ env/file 解析   repl（聚合 query+schema+format）
                               format ← result
-        cli（skill 子命令）─-> skillscheck ─-> bundle（根包，//go:embed skills/）
 ```
 
 - **`result`** - 共享 `Result{Columns, Rows, RowsAffected, LastInsertID}`，是 query/schema（生产者）与 format/cli（消费者）之间的中立契约。
@@ -47,10 +46,8 @@ cmd/mysql-cli/main  ->  cli（cobra 装配 + 退出码映射 + skill 子命令
 - **`query`** - `Execute`（读，走 `QueryContext`）、`ExecuteWrite`（单条 DML/DDL，包在事务里提交）、`ExecuteTxn`（多条原子事务）。每条语句都过 safety 闸门 + 多语句检测。
 - **`schema`** - 只读探索命令（`schema/sample/tables/databases/read/explore/analyze`），对应原 MCP 的 `get_schema_info`/`get_table_sample`/`list_resources`/`read_resource`。所有标识符在拼接 SQL 前经 `safety.Validate*` 校验。
 - **`format`** - `result.Result` -> json/table/csv/tsv；JSON 严格信封 `{success,data,error:{code,message}}`。
-- **`cli`** - cobra 子命令 + 全局 flag + `mapError` 把核心 error 翻译成退出码；含 `skill` 子命令（list/check/install/version）。
+- **`cli`** - cobra 子命令 + 全局 flag + `mapError` 把核心 error 翻译成退出码；含 `config` 子命令（init/list/global/project）。
 - **`repl`** - readline 交互壳，仅人类调试用，复用 query/schema/format。
-- **`bundle`**（根包，`bundle.go`）- `//go:embed skills` 把 skill 定义嵌入二进制，是 `mysql-cli skill install` 零依赖安装的单一来源（与 `scripts/install-skills.sh` 共享 `skills/` 目录）。
-- **`skillscheck`** - 对比已装 skill（如 `~/.claude/skills`）的 version frontmatter 与 bundle 内嵌版本，报 `ok/stale/missing/unknown`。仅 `mysql-cli skill check` 显式调用，**不走查询热路径**。
 
 ## 关键约定（改代码前必读）
 
@@ -76,12 +73,11 @@ cmd/mysql-cli/main  ->  cli（cobra 装配 + 退出码映射 + skill 子命令
 
 ## Skill 体系（对接 AI agent）
 
-skill 让 agent 零配置发现并正确调用 mysql-cli，设计参照 `larksuite/cli`（调研见 `docs/research-lark-cli.md`）。
+mysql-cli 的 skill 不再自研安装,而是接入 [vercel-labs/skills](https://github.com/vercel-labs/skills) 生态。skill 是仓库侧资产,由通用 `skills` 包管理器安装到 75+ agent。
 
-- **skill 文件**：`skills/mysql-{shared,query,schema}/SKILL.md`。`mysql-shared` 承载配置/安全模型/退出码/错误自修复，被 `mysql-query`/`mysql-schema` 顶部 `MUST Read` 引用（auto-load，DRY）。新增 skill 建 `skills/mysql-<name>/SKILL.md`，参考 `skill-template/skill-template.md`。
-- **安装**（二选一）：
-  - `./scripts/install-skills.sh` -- auto 检测已安装的 agent；原生支持 claude/cursor（SKILL.md/.mdc），codex/opencode/copilot/windsurf/aider 幂等追加合并 skill 到各自指令文件；支持 `--agent <name>|all`、`--project-dir`、`--no-global`。
-  - `mysql-cli skill install [target-dir]` -- 从二进制内嵌的 bundle 安装，零外部依赖（默认 `~/.claude/skills`）。
-- **版本同步检查**：`mysql-cli skill check [target-dir] [-j]` 对比已装 skill version 与内嵌版本，状态 `ok/stale/missing/unknown`，始终 exit 0（agent 解析 JSON `status` 字段）。
-- **格式校验**：`scripts/skill-format-check.sh` 校验 SKILL.md frontmatter（name/version/description/metadata + name 匹配目录 + semver），CI `.github/workflows/skill-format-check.yml` 在 PR 时强制。改 skill 后本地跑一遍。
-- **改动 skill 后**：skill 文件是 `bundle` 的 embed 源，改完 `go build` 重新嵌入；`scripts/install-skills.sh` 与 bundle 共享同一份 `skills/`，无需同步两份。
+- **skill 文件**:`skills/mysql-{shared,query,schema}/SKILL.md`。`mysql-shared` 承载配置/安全模型/退出码/错误自修复,被 `mysql-query`/`mysql-schema` 顶部 `MUST Read` 引用(auto-load,DRY)。
+- **安装**:`npx skills add AllenMuu/mysql-cli`(交互式选 agent/scope/install method);非交互 `npx skills add AllenMuu/mysql-cli --skill '*' -a <agent> -g -y`。**务必全装 3 个 skill**,否则 `mysql-shared` 引用断裂。
+- **发现机制**:仓库根 `.well-known/agent-skills/index.json` 声明 3 skill(vercel-labs/skills 首选);不加也可走默认 `skills/*/SKILL.md` 扫描。
+- **格式校验**:`scripts/skill-format-check.sh` 校验 SKILL.md frontmatter(name/version/description/metadata + semver),CI `.github/workflows/skill-format-check.yml` PR 时强制。改 skill 后本地跑一遍。
+- **版本真相源**:skill 版本 = 仓库 `skills/*/SKILL.md` frontmatter 的 `version` 字段(不再二进制内嵌)。
+- **无 Node fallback**:手动复制仓库 `skills/` 目录到 agent skill 目录。

CHANGELOG.md

@@ -5,6 +5,7 @@
 ### Breaking
 - **SELECT 默认安全 cap 1000**:不带 LIMIT 的 SELECT 现在默认只返回 1000 行,`meta.truncated=true` 标记截断。需全表用 `--no-limit`;调默认值用 config `default_limit` 或 env `MYSQL_CLI_DEFAULT_LIMIT`;显式精确行数用 `--limit N`。动机:实测裸跑 4.4 万行表 = ~900 万 token(45 个 200K context 窗口),会当场撑爆 agent 会话。
 - **SELECT 的 JSON 信封省略 `rows_affected`**(对 SELECT 恒为 0);改用 `meta.truncated`/`meta.limit`。DML/DDL 信封不变。
+- **skill 安装迁移至 vercel-labs/skills 生态**:`mysql-cli init`、`mysql-cli skill install/list/version/check` 及 `scripts/install-skills.sh` 全部移除。改用 `npx skills add AllenMuu/mysql-cli` 安装 skill(支持 75+ agent,交互式选 agent/scope/install method)。无 Node 环境可手动复制仓库 `skills/` 目录。skill 版本真相源从二进制内嵌迁移至仓库 `skills/*/SKILL.md` frontmatter。
 
 ### Added
 - `--format jsonl`:每行一个 JSON 对象,比 json 紧凑,适合 agent。

README-zh.md

@@ -102,22 +102,25 @@ go install github.com/AllenMuu/mysql-cli/cmd/mysql-cli@latest
 
 **第 2 步 - 安装 Agent Skills**
 
-二选一(两种方式都会安装全部三个 skill):
-
-*方式 A - 安装脚本*(支持下列所有 agent):
+通过 [vercel-labs/skills](https://github.com/vercel-labs/skills) 安装 skill(支持 70+ 种 agent):
 
 ```bash
-./scripts/install-skills.sh                              # 自动检测
-./scripts/install-skills.sh --agent all --project-dir ~/my-project
+npx skills add AllenMuu/mysql-cli
 ```
 
-*方式 B - 从二进制安装*(内嵌 skill,零外部依赖):
+会打开交互式选择:选 agent、选 scope(project `./<agent>/skills/` 或 global `~/<agent>/skills/`)、选安装方式(推荐 symlink)、确认。
+
+非交互(CI / agent):
 
 ```bash
-mysql-cli skill install                       # -> ~/.claude/skills
-mysql-cli skill install ~/my-project/.claude/skills
+npx skills add AllenMuu/mysql-cli --skill '*' -a claude-code -g -y
 ```
 
+> **务必安装全部 3 个 skill**(`mysql-shared`、`mysql-query`、`mysql-schema`)。
+> `mysql-query` 与 `mysql-schema` 顶部引用 `../mysql-shared/SKILL.md`,只装单个会导致引用断裂。
+
+**无 Node.js?** 手动把仓库 `skills/` 目录复制到 agent 的 skill 目录(如 `~/.claude/skills/`)。
+
 **第 3 步 - 配置数据源**
 
 写入 `~/.config/mysql-cli/config.toml`(完整格式见[配置](#配置)):
@@ -136,7 +139,6 @@ database = "app"
 **第 4 步 - 验证并执行**
 
 ```bash
-mysql-cli skill check                                 # 确认 skill 与二进制版本一致
 mysql-cli query "SELECT * FROM users LIMIT 10"        # 默认 JSON 输出
 ```
 
@@ -273,28 +275,17 @@ Skills 编码了触发条件、前置检查、命令参考、安全模型与错
 
 ### 其他 agent
 
-`mysql-cli` 兼容**任何能跑 shell 命令并解析 JSON 的 agent**。安装脚本支持下列全部七种
-agent:Claude Code 与 Cursor 使用原生 SKILL.md / .mdc 格式;其余 agent 会把合并后的 skill
-正文(幂等地)追加到各自的指令文件。
+`mysql-cli` 兼容**任何能跑 shell 命令并解析 JSON 的 agent**。`npx skills add` 安装器(vercel-labs/skills)支持 Claude Code、Cursor、Codex 以及 70+ 种 agent;它以 symlink 方式安装每个 skill,因此更新仓库即可自动同步。
 
-| Agent | 配置格式 | 如何使用 `mysql-cli` |
+| Agent | 配置格式 | 安装 |
 | --- | --- | --- |
-| **Claude Code** | `.claude/skills/*/SKILL.md` | `./scripts/install-skills.sh --agent claude` 或 `mysql-cli skill install` |
-| **Cursor** | `.cursor/rules/*.mdc` | `./scripts/install-skills.sh --agent cursor` |
-| **Codex CLI** | `AGENTS.md` | `./scripts/install-skills.sh --agent codex` |
-| **OpenCode** | `.opencode/instructions.md` | `./scripts/install-skills.sh --agent opencode` |
-| **GitHub Copilot** | `.github/copilot-instructions.md` | `./scripts/install-skills.sh --agent copilot` |
-| **Windsurf** | `.windsurfrules` | `./scripts/install-skills.sh --agent windsurf` |
-| **Aider** | `.aider.instructions.md` | `./scripts/install-skills.sh --agent aider`(然后在 `.aider.conf.yml` 加 `read:`) |
-
-### Skill 管理命令
-
-| 命令 | 说明 |
-| --- | --- |
-| `mysql-cli skill list` | 列出二进制内嵌的 skill |
-| `mysql-cli skill version` | 打印期望的 skill 版本 |
-| `mysql-cli skill check [dir] [-j]` | 对比已装版本与内嵌版本(`ok`/`stale`/`missing`) |
-| `mysql-cli skill install [dir]` | 把内嵌 skill 安装到指定目录 |
+| **Claude Code** | `.claude/skills/*/SKILL.md` | `npx skills add AllenMuu/mysql-cli -a claude-code` |
+| **Cursor** | `.cursor/rules/*.mdc` | `npx skills add AllenMuu/mysql-cli -a cursor` |
+| **Codex CLI** | `AGENTS.md` | `npx skills add AllenMuu/mysql-cli -a codex` |
+| **OpenCode** | `.opencode/instructions.md` | `npx skills add AllenMuu/mysql-cli -a opencode` |
+| **GitHub Copilot** | `.github/copilot-instructions.md` | `npx skills add AllenMuu/mysql-cli -a github-copilot` |
+| **Windsurf** | `.windsurfrules` | `npx skills add AllenMuu/mysql-cli -a windsurf` |
+| **Aider** | `.aider.instructions.md` | `npx skills add AllenMuu/mysql-cli -a aider`(然后在 `.aider.conf.yml` 加 `read:`) |
 
 ### 安装须知
 

README.md

@@ -52,10 +52,10 @@ binary with **JSON by default** and **stable exit codes**, so any agent
 
 ```bash
 npx @allenmuu/mysql-cli install      # installs the prebuilt binary to ~/.local/bin
-mysql-cli init                       # installs agent skills into detected agents
+npx skills add AllenMuu/mysql-cli    # installs agent skills (interactive)
 ```
 
-The `npx` command downloads the prebuilt binary for your platform from GitHub Releases. Set `MYSQL_CLI_MIRROR` to use a download mirror. Then run `mysql-cli init` to install skills.
+The `npx` command downloads the prebuilt binary for your platform from GitHub Releases. Set `MYSQL_CLI_MIRROR` to use a download mirror. Then run `npx skills add AllenMuu/mysql-cli` to install skills.
 
 **Option 2 - `go install`:**
 
@@ -115,30 +115,29 @@ go install github.com/AllenMuu/mysql-cli/cmd/mysql-cli@latest
 
 **Step 2 - Install Agent Skills**
 
-Choose one (all install the three skills). **Option 0 is the recommended approach**:
-
-**Option 0 - `mysql-cli init` (recommended, no repo clone needed):**
+mysql-cli ships skills for AI agents (Claude Code, Cursor, Codex, and 70+ more)
+via the [vercel-labs/skills](https://github.com/vercel-labs/skills) ecosystem.
 
 ```bash
-mysql-cli init                       # auto-detect installed agents, install to global
-mysql-cli init --agent all           # install for all 7 agents
-mysql-cli init --project-dir ~/my-project --no-global  # project-level only
-mysql-cli init -j                    # JSON output for agents
+npx skills add AllenMuu/mysql-cli
 ```
 
-*Option A - installer script* (supports all agents below):
+This opens an interactive picker: select agents, choose scope (project
+`./<agent>/skills/` or global `~/<agent>/skills/`), choose install method
+(symlink recommended), and confirm.
+
+Non-interactive (CI / agents):
 
 ```bash
-./scripts/install-skills.sh                              # auto-detect
-./scripts/install-skills.sh --agent all --project-dir ~/my-project
+npx skills add AllenMuu/mysql-cli --skill '*' -a claude-code -g -y
 ```
 
-*Option B - from the binary* (embeds skills, zero external deps):
+> **Install all three skills** (`mysql-shared`, `mysql-query`, `mysql-schema`).
+> `mysql-query` and `mysql-schema` reference `../mysql-shared/SKILL.md`; installing
+> only one breaks the shared-rules reference.
 
-```bash
-mysql-cli skill install                       # -> ~/.claude/skills
-mysql-cli skill install ~/my-project/.claude/skills
-```
+**No Node.js?** Manually copy the `skills/` directory from this repo into your
+agent's skill directory (e.g. `~/.claude/skills/`).
 
 **Step 3 - Configure a datasource**
 
@@ -158,7 +157,6 @@ database = "app"
 **Step 4 - Verify & run**
 
 ```bash
-mysql-cli skill check                                 # confirm skills match the binary
 mysql-cli query "SELECT * FROM users LIMIT 10"        # JSON by default
 ```
 
@@ -301,28 +299,19 @@ There are three skills, following the shared-skill pattern from `larksuite/cli`:
 ### Other agents
 
 `mysql-cli` works with **any agent that can run shell commands and parse
-JSON**. The installer supports all seven agents below: Claude Code and Cursor
-use the native SKILL.md / .mdc formats; the others receive the merged skill
-body appended (idempotently) to their instruction files.
+JSON**. The `npx skills add` installer (vercel-labs/skills) supports Claude
+Code, Cursor, Codex, and 70+ more agents; it symlinks each skill into the
+agent's skill directory.
 
-| Agent | Config format | How to use `mysql-cli` |
+| Agent | Config format | Install |
 | --- | --- | --- |
-| **Claude Code** | `.claude/skills/*/SKILL.md` | `./scripts/install-skills.sh --agent claude` or `mysql-cli skill install` |
-| **Cursor** | `.cursor/rules/*.mdc` | `./scripts/install-skills.sh --agent cursor` |
-| **Codex CLI** | `AGENTS.md` | `./scripts/install-skills.sh --agent codex` |
-| **OpenCode** | `.opencode/instructions.md` | `./scripts/install-skills.sh --agent opencode` |
-| **GitHub Copilot** | `.github/copilot-instructions.md` | `./scripts/install-skills.sh --agent copilot` |
-| **Windsurf** | `.windsurfrules` | `./scripts/install-skills.sh --agent windsurf` |
-| **Aider** | `.aider.instructions.md` | `./scripts/install-skills.sh --agent aider` (then add `read:` to `.aider.conf.yml`) |
-
-### Skill management commands
-
-| Command | Description |
-| --- | --- |
-| `mysql-cli skill list` | List skills bundled with this binary |
-| `mysql-cli skill version` | Print expected skill versions |
-| `mysql-cli skill check [dir] [-j]` | Compare installed vs bundled versions (`ok`/`stale`/`missing`) |
-| `mysql-cli skill install [dir]` | Install bundled skills into a directory |
+| **Claude Code** | `.claude/skills/*/SKILL.md` | `npx skills add AllenMuu/mysql-cli -a claude-code` |
+| **Cursor** | `.cursor/rules/*.mdc` | `npx skills add AllenMuu/mysql-cli -a cursor` |
+| **Codex CLI** | `AGENTS.md` | `npx skills add AllenMuu/mysql-cli -a codex` |
+| **OpenCode** | `.opencode/instructions.md` | `npx skills add AllenMuu/mysql-cli -a opencode` |
+| **GitHub Copilot** | `.github/copilot-instructions.md` | `npx skills add AllenMuu/mysql-cli -a github-copilot` |
+| **Windsurf** | `.windsurfrules` | `npx skills add AllenMuu/mysql-cli -a windsurf` |
+| **Aider** | `.aider.instructions.md` | `npx skills add AllenMuu/mysql-cli -a aider` (then add `read:` to `.aider.conf.yml`) |
 
 ### Setup notes
 

dist/npm/README.md

@@ -6,16 +6,16 @@ One-line install of the [mysql-cli](https://github.com/AllenMuu/mysql-cli) Go bi
 
 ```bash
 npx @allenmuu/mysql-cli install      # installs the binary to ~/.local/bin
-mysql-cli init                       # installs agent skills (auto-detected)
+mysql-cli config init                  # initialises config (auto-detected)
 ```
 
 No Go toolchain required. The `install` command downloads the prebuilt binary for your platform from GitHub Releases.
 
 ## One-shot usage (no permanent install)
 
 ```bash
-npx @allenmuu/mysql-cli init         # install skills into detected agents
-npx @allenmuu/mysql-cli skill check  # check installed skill versions
+npx @allenmuu/mysql-cli config init  # initialises config (same as above)
+npx @allenmuu/mysql-cli config list  # list configured datasources
 npx @allenmuu/mysql-cli query "SELECT 1" -d mydb
 ```