@teamix-evo/skills

Skills (AI IDE 自动技能) for Teamix Evo. 同源支持 Qoder、Claude Code 和 Codex / ChatGPT。

包结构

packages/skills/
├── manifest.json          # 顶层声明：枚举所有 skill
├── _data.json             # 模板共享数据（可选）
├── _template/             # 新建 skill 时的脚手架模板
│   └── SKILL.md.hbs
├── src/                   # 每个发布的 skill 一个子目录
│   ├── teamix-evo-manage/
│   │   ├── SKILL.md       # 生命周期、自更新与嵌入式应用边界
│   │   ├── scripts/check-self-update.mjs # 零 npm 缓存的 Registry 版本检查
│   │   ├── style-isolation.md
│   │   ├── scoped-preflight.md
│   │   ├── rearchitect.md
│   │   ├── update*.md     # 升级与 token 处理子流程
│   │   └── scripts/       # scoped preflight generator
│   └── teamix-evo-{design,code}-*/ # 变体设计与编码 skill
└── scripts/
    ├── design-skill-health.test.ts
    ├── manage-def-exclusion-contract.test.ts
    ├── manage-self-update-contract.test.ts
    ├── project-ui-skill-contract.test.ts
    ├── validate-skills.ts
    ├── scaffold-skill.ts
    ├── scoped-preflight.test.mjs
    └── scoped-preflight.browser.spec.mjs

协议要点

• 每个 skill 必须有 SKILL.md，frontmatter 至少包含 name + description。
• description 是 AI 触发依据，请明确写出"何时该激活"。
• 默认 updateStrategy: managed，并使用 managed regions 让升级保留用户自定义部分。
• 安装后 SKILL.md 同时落到所选 IDE 路径：
  • Qoder：.qoder/skills/<name>/SKILL.md 或 ~/.qoder/skills/<name>/SKILL.md
  • Claude：.claude/skills/<name>/SKILL.md 或 ~/.claude/skills/<name>/SKILL.md
  • Codex / ChatGPT：.agents/skills/<name>/SKILL.md 或 ~/.agents/skills/<name>/SKILL.md

研发态命令

# 校验 manifest + 资源完整性
pnpm --filter @teamix-evo/skills validate

# 首次运行浏览器回归前安装 Playwright 配套 Headless Shell
pnpm --filter @teamix-evo/skills exec playwright install --only-shell chromium

# 运行全部测试（含 Scoped Preflight 真实浏览器 cascade）
pnpm --filter @teamix-evo/skills test

# 仅运行真实浏览器 cascade
pnpm --filter @teamix-evo/skills test:browser

# 仅运行 manage 自更新、DEF/O2 排除与 Project UI 契约
pnpm --filter @teamix-evo/skills test:manage-self-update-contract
pnpm --filter @teamix-evo/skills test:manage-def-exclusion-contract
pnpm --filter @teamix-evo/skills test:project-ui-contract

# 新建 skill（脚手架）
pnpm --filter @teamix-evo/skills scaffold:skill

Scoped Preflight 浏览器回归使用 Playwright 管理的隔离 Chromium，不探测或启动 开发机安装的系统 Chrome。CI 必须显式执行 playwright install --only-shell chromium 后再运行测试，确保浏览器版本与 @playwright/test 精确匹配。macOS Codex Seatbelt 不允许 Chromium 注册所需的 Mach 服务，因此该环境会明确显示一项 skipped；GitHub CI 与普通本地终端仍执行 真实浏览器门禁。

消费态命令（CLI）

由 teamix-evo skills 子命令族管理（npm 包直接渲染到 IDE 镜像，见 ADR 0048）：

teamix-evo skills init               # 自举：按 variant + scope 全装符合条件的 skill（ADR 0034）
teamix-evo skills add <name...>      # 增量：仅装入指定 skill（必填，至少一个）
teamix-evo skills list               # 列出全部 skill（默认：已装✓ / 未装○）
teamix-evo skills update [name...] [--dry-run]  # 升级已装 skill（ADR 0035 双闸 + version 短路）
teamix-evo skills sync [name...]     # npm 包 → IDE 镜像（漂移恢复用）
teamix-evo skills doctor             # 检测 IDE 镜像缺失 / 漂移
teamix-evo skills uninstall          # 卸载已知 IDE 镜像 + lock 记录

verb 分工(ADR 0034):init 自举(无 ids)/ add 增量(必填 ids)。skills add 不传 id → commander 报错并输出 help。

scope 过滤(ADR 0033):skills init 跳过 manifest 里 scope 与当前 install scope 不匹配的 entry。entry skill teamix-evo-manage 标 scope: "global",因此项目级 init 不会重复装入 —— 它由「全局装机」段一次性装到全局。skills add 显式指名 global-only skill 时仍可装入并得到 warning；后续必须显式执行 skills update teamix-evo-manage --scope project 才会更新这个 override，批量 update 不会触碰它。

全局装机（--scope global）

# 一行装到三个 IDE 的用户级 skill 目录，元数据落到 ~/.teamix-evo-global/
npx teamix-evo@latest skills add teamix-evo-manage --scope global --ide qoder,claude,codex -y

# 后续维护（update / uninstall 等）需 cd 到全局元数据根
cd ~/.teamix-evo-global && npx teamix-evo skills update

已有项目补充 Codex mirror：

npx teamix-evo@latest skills sync --ide qoder,claude,codex