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

Claude技能管理仓库

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

English | 中文

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

仓库结构

.
├── 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

快速开始

pnpm install
pnpm skills:validate
pnpm skills:index
pnpm dev

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

安装技能

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

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/* 下添加或复制了技能的情况）：

pnpm skills:finalize:new

预演（dry-run）：

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

推荐快捷路径：

pnpm skills:new

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

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

非交互式创建示例：

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

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

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

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

# 相对路径
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。

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

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

交互式菜单流程：

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

同样支持非交互式模式：

# 安装单个技能（如需多个可重复 --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 发布和回滚策略）。