catalog/repos/adonis0123--adonis-skills.md

# Claude技能管理仓库

`monorepo` `AI技能` `Next.js` `CLI工具` `自动化`

English | [中文](./README.zh-CN.md)

# adonis-skills

`adonis-skills` 是一个以智能体为中心的技能仓库，采用 `pnpm + Turborepo + Next.js 16` monorepo 架构构建。

目标：

- 让技能可通过 `npx skills add` 直接安装
- 提供展示技能元数据和安装命令的 Web UI
- 为未来演进保留空间（更多技能、可选 npm 发布）

**在线站点**：<https://adonis-skills.vercel.app/>

## 当前状态

- 公开技能：`commit`、`staged-review-validator`、`tailwindcss-next-init`、`weekly-report`
- Web 站点：`apps/web`（Next.js 16）
- 技能目录：`skills/*`
- 技能索引生成：`scripts/generate-skills-index.mjs`
- 技能结构校验：`scripts/validate-skills.mjs`

## 仓库结构

```txt
.
├── apps/
│   └── web/
├── skills/
│   ├── commit/
│   ├── staged-review-validator/
│   ├── tailwindcss-next-init/
│   └── weekly-report/
├── scripts/
│   ├── generate-skills-index.mjs
│   └── validate-skills.mjs
├── turbo.json
├── pnpm-workspace.yaml
└── .github/workflows/ci.yml
```

## 快速开始

```bash
pnpm install
pnpm skills:validate
pnpm skills:index
pnpm dev
```

在浏览器中打开 `http://localhost:3000`。

## 安装技能

默认仓库标识符：`adonis0123/adonis-skills`

```bash
npx skills add adonis0123/adonis-skills --skill weekly-report
npx skills add adonis0123/adonis-skills --skill tailwindcss-next-init
```

若仓库所有者发生变更：

1. 设置 `NEXT_PUBLIC_SKILLS_REPO=<新所有者>/adonis-skills`（例如写入 `.env.local`）
2. 重启 `pnpm dev`（或重新部署）以应用新值

## 命令速查表（每条命令的作用）

下表说明 `package.json` 中各脚本的含义。

| 命令 | 实际执行 | 含义 / 使用场景 |
| --- | --- | --- |
| `pnpm dev` | `turbo run dev --filter=@adonis-skills/web` | 启动 Web 站点开发模式（仅 `apps/web`）。用于日常本地 UI 调试。 |
| `pnpm build` | `turbo run build` | 运行 monorepo 构建任务。提交变更前确认仓库可正常构建时使用。 |
| `pnpm lint` | `turbo run lint` | 执行代码风格/lint 检查。修改 TS/JS 文件后使用。 |
| `pnpm typecheck` | `turbo run typecheck` | 运行 TypeScript 类型检查。修改类型/API 后使用。 |
| `pnpm skills:new` | `node --experimental-strip-types ./scripts/create-skill.ts` | 创建新技能的交互式入口。自动执行：初始化 -> 快速校验 -> 完整校验 -> 刷新索引。 |
| `pnpm skills:finalize -- <skill-path>` | `node --experimental-strip-types ./scripts/finalize-skill.ts` | 对 `skills/*` 下已有或复制的技能执行标准 finalize 流程：`quick-validate` -> `validate` -> `index`。支持相对路径和绝对路径。 |
| `pnpm skills:finalize:new [-- --dry-run]` | `node --experimental-strip-types ./scripts/finalize-new-skills.ts` | 自动模式：仅检测 `skills/<slug>/SKILL.md` 状态为 `A` 或 `??` 的新增技能，逐个执行 finalize，然后暂存相关文件（`skills/<slug>` 及变更的技能索引）。若未发现新技能，则回退到 `skills:new` 并重新扫描。 |
| `pnpm skills:init <skill-name> --path skills` | `python3 ./.agents/skills/repo-skill-creator/scripts/init_skill.py` | 仅初始化技能目录/模板内容（手动模式）。不需要完整自动化流程时使用。 |
| `pnpm skills:quick-validate skills/<skill-name>` | `python3 ./.agents/skills/repo-skill-creator/scripts/quick_validate.py` | 校验单个技能（尤其是 frontmatter 合法性）。编辑单个技能后作为快速本地检查使用。 |
| `pnpm skills:openai-yaml <skill-dir>` | `python3 ./.agents/skills/repo-skill-creator/scripts/generate_openai_yaml.py` | 为技能生成 `agents/openai.yaml`（OpenAI 技能接口元数据）。需要接口元数据时使用。 |
| `pnpm skills:validate` | `turbo run skills:validate --filter=@adonis-skills/web` | 全仓库技能校验。提交/CI 前必须执行。 |
| `pnpm skills:index` | `turbo run skills:index --filter=@adonis-skills/web` | 重新生成 `apps/web/src/generated/skills-index-lite.json` 和 `apps/web/src/generated/skills-detail-index.json`。添加或更新技能后执行，保持 Web 数据最新。 |
| `pnpm skills:install:local` | `node --experimental-strip-types ./scripts/install-local-skills.ts` | 将 `skills/` 中的技能安装到本地 `.agents/skills`（支持交互式选择、`--all`、`--skill`）。用于本地智能体测试。 |
| `pnpm skills:test:local` | `node --experimental-strip-types ./scripts/install-local-skills.ts --sync-llm` | 先本地安装，再同步到 `.claude/skills`。在本地 Claude/Codex 运行时中测试时使用。 |
| `pnpm skills:sync:llm` | `node --experimental-strip-types ./scripts/sync-llm-skills.ts` | 原子性地将 `.agents/skills` 同步到 `.claude/skills`。仅需重新执行同步时使用。 |
| `pnpm ruler:apply` | `pnpm dlx @intellectronica/ruler@latest apply --local-only --no-backup` | 根据 `.ruler/*` 生成/更新根目录产物（如 `AGENTS.md` 和 `CLAUDE.md`）。修改规则后执行。 |
| `pnpm postinstall` | 条件性 postinstall 钩子（本地执行 `ruler:apply` 和 `skills:sync:llm`；CI 中跳过） | 由 `pnpm install` 触发：本地环境执行 `ruler:apply` 和 `skills:sync:llm`；CI 跳过。 |

注意：

- 默认直接流程（无路径）：`skills:finalize:new`
- 新技能最常用流程：`skills:new` -> `skills:validate` -> `skills:index`
- 最常用手动流程：`skills:init`（或手动复制）-> `skills:finalize -- <skill-path>`

## 新技能标准流程（SOP）

自动模式（推荐，适用于已在 `skills/*` 下添加或复制了技能的情况）：

```bash
pnpm skills:finalize:new
```

预演（dry-run）：

```bash
pnpm skills:finalize:new -- --dry-run
```

推荐快捷路径：

```bash
pnpm skills:new
```

默认以交互式方式收集 `name`、`description`、可选资源目录，然后依次执行：

1. 初始化技能目录（默认路径：`skills/`）
2. 单技能快速校验（`skills:quick-validate`）
3. 全仓库校验（`skills:validate`）
4. 索引重新生成（`skills:index`）

非交互式创建示例：

```bash
pnpm skills:new -- --name demo-skill --description "用于演示新技能工作流" --resources scripts,references --non-interactive
```

手动模式（先初始化或复制，再 finalize）：

```bash
pnpm skills:init <skill-name> --path skills --resources scripts,references
pnpm skills:finalize -- skills/<skill-name>
```

仅执行 finalize（无需重新初始化）：

```bash
# 相对路径
pnpm skills:finalize -- skills/code-inspector-init

# 绝对路径（末尾 / 会自动处理）
pnpm skills:finalize -- /Users/adonis/coding/adonis-skills2/skills/code-inspector-init/

# 仅预览命令，不实际执行
pnpm skills:finalize -- --dry-run skills/code-inspector-init
```

## 本地交互式安装与测试

本仓库支持将 `skills/` 中的技能安装到 `.agents/skills`，并可选择同步到 `.claude/skills`。

```bash
# 默认：进入交互式菜单（选择 + 复选框）
pnpm skills:install:local

# 交互式安装后，一键同步到 .claude/skills
pnpm skills:test:local
```

交互式菜单流程：

1. 选择 `安装选定技能` / `安装全部技能` / `退出`
2. 若选择部分安装，进入多选列表（空格键勾选）
3. 确认并执行安装

同样支持非交互式模式：

```bash
# 安装单个技能（如需多个可重复 --skill）
pnpm skills:install:local -- --no-interactive --skill weekly-report

# 安装全部
pnpm skills:install:local -- --no-interactive --all

# 非交互式安装后同步
pnpm skills:test:local -- --no-interactive --skill weekly-report
```

注意：

- 安装命令底层使用 `npx skills add ./skills -a codex ...`，目标目录为 `.agents/skills`
- `skills:test:local` 在安装后执行 `skills:sync:llm`，将 `.agents/skills` 镜像到 `.claude/skills`

## CI

GitHub Actions 执行：

- `pnpm install --frozen-lockfile`
- `pnpm skills:validate`
- `pnpm skills:index`
- `pnpm --filter @adonis-skills/web run i18n -- --compile --strict`
- `pnpm turbo run lint typecheck build --filter=@adonis-skills/web`

各步骤校验内容：

- `install`：基于锁文件的一致性依赖安装
- `skills:validate`：`skills/*` 的 frontmatter/schema 合法性
- `skills:index`：重新生成 `apps/web/src/generated/skills-index.json`
- `Prepare i18n Catalogs`：将 `src/locales/**/*.po` 编译为 `*.mjs`，并重新生成 `src/i18n/catalog-manifest.ts`
- `lint/typecheck/build`：代码质量、TS 正确性及生产构建可用性

i18n 步骤为何必须执行：

- 编译后的 Lingui 目录（`src/locales/**/*.mjs`）被 git 刻意忽略。
- `src/i18n/catalog-manifest.ts` 导入了这些 `.mjs` 文件。
- 若 CI 中未预先编译目录，`typecheck` 会因 `TS2307`（"找不到模块 .../src/locales/.../*.mjs"）而失败。

常见失败类别：

- 依赖/安装问题（`pnpm install`）
- 技能校验失败（`pnpm skills:validate`）
- i18n 编译/翻译严格检查失败（`Prepare i18n Catalogs`）
- TypeScript 模块/类型错误（`typecheck`）

排错规则：

- 若看到 `TS2307` 错误路径指向 `src/locales/**/*.mjs`，请先执行 `pnpm --filter @adonis-skills/web run i18n -- --compile`，再重新运行 typecheck。

失败将阻断合并，以确保 main 分支始终可部署。

## Vercel 部署（自动）

本仓库推荐的 Vercel 设置：

- 安装命令：`pnpm install --frozen-lockfile`
- 构建命令：`pnpm turbo run build --filter=@adonis-skills/web`
- 输出目录：默认 Next.js 输出（无需手动覆盖）

main 分支更新后，Vercel 自动部署。若出现问题版本，在 GitHub 回退到上一个绿色提交即可。

## 未来计划

V1 仅支持 GitHub 安装流程。后续可添加 npm 发布支持（包括 GitHub Action 发布和回滚策略）。