# xycomponents AI Skills

面向 Cursor、Claude Code、Codex 与其他读取 `AGENTS.md` 的 Agent。配合项目内安装的 `@czxingyu/xycomponents` 使用。

## 原则

- **CLI 与组件库版本一致**：在业务项目中 `pnpm add @czxingyu/xycomponents`，用 `pnpm exec xycomponents` 查询；升级库时重新 `pnpm add`，CLI 随包更新。
- **不要全局安装** CLI，避免 AI 查到与项目不一致的 API。
- **Bug / 新组件**：业务项目 AI 用 `xycomponents-contribute` 提交 GitHub Issue；组件库维护者用 `xycomponents-maintainer` 集中分诊与修复。

## 自动安装（推荐）

安装组件库后，Skill 会**自动**写入当前项目（可用环境变量跳过）：

```bash
pnpm add @czxingyu/xycomponents
# postinstall 会自动执行：pnpm exec xycomponents skills install --consumer --json
```

跳过自动安装：

```bash
XYCOMPONENTS_SKIP_SKILLS_INSTALL=1 pnpm add @czxingyu/xycomponents
```

手动重装 / 升级后同步 Skill：

```bash
pnpm exec xycomponents skills install --consumer --json
```

维护者额外安装 maintainer skill：

```bash
pnpm exec xycomponents skills install --maintainer --json
```

## 支持的 Agent 目录

| 目标        | 目录              | 典型工具                            |
| ----------- | ----------------- | ----------------------------------- |
| `cursor`    | `.cursor/skills/` | Cursor                              |
| `claude`    | `.claude/skills/` | Claude Code                         |
| `codex`     | `.codex/skills/`  | Codex                               |
| `agents`    | `.agents/skills/` | 通用 Agent 技能目录                 |
| `AGENTS.md` | 项目根目录        | ChatGPT / 其他读取 AGENTS.md 的工具 |

默认 `--target all` 会写入以上全部目录，并更新 `AGENTS.md` 引导块。

只装 Cursor：

```bash
pnpm exec xycomponents skills install --consumer --target cursor
```

## 完整闭环

```text
业务项目                         组件库仓库 (vue3components)
────────                         ──────────────────────────
pnpm add @czxingyu/xycomponents
  └─ postinstall / skills install
pnpm exec xycomponents ...  ──►   查用法 / API
       │
       ▼ Bug 或 Feature
gh issue create (contribute) ──►  needs-triage 队列
                                 maintainer skill 拉取 Issue
                                 修复 / 新增组件 / 发版
       ▲
pnpm add @新版本 ◄───────────────  关闭 Issue，注明版本
```

## Skill 列表

| Skill                                                         | 谁用         | 用途                         |
| ------------------------------------------------------------- | ------------ | ---------------------------- |
| [xycomponents-shared](./xycomponents-shared/SKILL.md)         | 业务项目     | 安装、版本策略、Vue 接入     |
| [xycomponents-cli](./xycomponents-cli/SKILL.md)               | 业务项目     | CLI 查询 Props / 示例        |
| [xycomponents-contribute](./xycomponents-contribute/SKILL.md) | 业务项目     | 提交 Bug / Feature Issue     |
| [xycomponents-maintainer](./xycomponents-maintainer/SKILL.md) | 组件库维护者 | 拉取 Issue、分诊、修复、发版 |

提交 Issue 需本机安装 [GitHub CLI](https://cli.github.com/) 并 `gh auth login`。

## GitHub Issue 模板

| 模板                                                 | 标签                          | 场景              |
| ---------------------------------------------------- | ----------------------------- | ----------------- |
| [bug.yml](../.github/ISSUE_TEMPLATE/bug.yml)         | `bug`, `needs-triage`         | 可复现缺陷        |
| [feature.yml](../.github/ISSUE_TEMPLATE/feature.yml) | `enhancement`, `needs-triage` | 新组件或 API 增强 |

用法问题优先 [Discussions](https://github.com/czhang31795/vue3components/discussions)。

## 验证

```bash
pnpm exec xycomponents doctor --json
pnpm exec xycomponents skills install --consumer --dry-run --json
```