johnQ
d43b414fc9
- 新增 SCOPE.md 收录门槛 + .out-of-scope/ 拒绝档案 - 生命周期分桶 promoted/beta/deprecated，marketplace 只发布 promoted - 调用模式 model-invoked/user-invoked（user-invoked 不占模型目录） - 新增脚本 validate-skills.py / generate-catalog.py / scan-skill.sh(+allowlist) - 新增 beta 技能 skill-creator、ai-proj-helper-entry、verification-before-completion（各带 evals） - install-skills.sh: --agent dsh / --link / --audit / --include-beta / --no-validate - 融合：dev-review 接收评审意见、req-design 依赖边、agent-swarm 并行编排、dev-test TDD - catalog.json 61 个技能（58 promoted / 3 beta）；validate 0 错误；scan 0 高危；现有测试通过
91 lines
3.4 KiB
Markdown
91 lines
3.4 KiB
Markdown
# Skill Sync Guide
|
||
|
||
仓库中的插件是团队技能的发布源。默认安装目标是 Codex 的用户级标准目录 `~/.agents/skills/`。个人技能保留在
|
||
`skills-personal/` 或其他本机目录，不会进入公开 marketplace。
|
||
|
||
## 从仓库更新本机
|
||
|
||
```bash
|
||
git pull
|
||
./install-skills.sh --dry-run
|
||
./install-skills.sh
|
||
```
|
||
|
||
Claude Code 需要显式选择目标：
|
||
|
||
```bash
|
||
./install-skills.sh --agent claude
|
||
```
|
||
|
||
安装器会复制完整技能目录，包括 `SKILL.md`、`references/`、`scripts/` 和 `assets/`。它用内容摘要区分仓库升级和本地修改：
|
||
|
||
- 目标未修改时，版本升级会自动安装。
|
||
- 旧版只安装了 `SKILL.md` 时，会安全补齐仓库中的其他同源文件。
|
||
- 目标存在本地修改时会跳过；确认覆盖后才使用 `--force`。
|
||
- `--cleanup` 会删除状态文件记录中已从仓库移除的技能，使用前先运行 `--dry-run --cleanup`。
|
||
|
||
按分类安装或查看清单：
|
||
|
||
```bash
|
||
./install-skills.sh --list
|
||
./install-skills.sh --category dev
|
||
./install-skills.sh --exclude ai-proj-cicd-release
|
||
```
|
||
|
||
## 将本机技能发布到仓库
|
||
|
||
不要批量复制整个 `~/.agents/skills/` 或其他 Agent 的安装目录。系统技能、第三方托管技能、包含机器路径或凭据的技能不应发布。
|
||
|
||
1. 选择确实属于本仓库、可供团队复用的技能。
|
||
2. 在对应 `skills-*/<name>-plugin/` 下放置 `.claude-plugin/plugin.json` 和完整 `skills/` 目录。
|
||
3. 清除用户名、绝对路径、内网地址、密钥标识和历史凭据；把环境差异改为从仓库配置解析。
|
||
4. 更新插件版本并运行：
|
||
|
||
```bash
|
||
python3 generate-marketplace.py
|
||
claude plugin validate .
|
||
git diff --check
|
||
```
|
||
|
||
5. 审核变更后通过分支和 PR 发布。
|
||
|
||
## 本地个人技能
|
||
|
||
`skills-personal/` 受 `.gitignore` 保护，仅供当前机器使用。生成器明确排除此目录，避免
|
||
`marketplace.json` 引用公开克隆中不存在的文件。若个人技能要转为团队技能，应先按上面的发布流程完成脱敏和审核。
|
||
|
||
## 常见问题
|
||
|
||
**本地修改被跳过怎么办？**
|
||
|
||
先比较仓库源和 `~/.agents/skills/<name>/`。保留本地修改时将其整理成插件变更；确认丢弃时再对该次安装使用 `--force`。Claude 目标改查 `~/.claude/skills/`。
|
||
|
||
**marketplace 没更新？**
|
||
|
||
运行 `python3 generate-marketplace.py`，然后检查 `.claude-plugin/marketplace.json` 是否只包含受 Git 跟踪且真实存在的 source。
|
||
|
||
**如何移除技能？**
|
||
|
||
删除插件目录、重新生成 marketplace、提交变更。使用者随后执行 `./install-skills.sh --dry-run --cleanup`，确认后再去掉 `--dry-run`。
|
||
|
||
## 安装矩阵（2026-10 更新）
|
||
|
||
| agent | 安装目录 | 默认模式 | 状态文件 |
|
||
| --- | --- | --- | --- |
|
||
| `codex`（默认） | `~/.agents/skills` | copy | `~/.agents/.ai-proj-helper-installed-skills.json` |
|
||
| `dsh` | `$DSH_HOME/skills` | copy（开发机建议 `--link`） | `$DSH_HOME/.ai-proj-helper-installed-skills.json` |
|
||
| `claude`（兼容） | `~/.claude/skills` | copy | `~/.claude/.installed-skills.json` |
|
||
|
||
```bash
|
||
# 本机（DSH 开发机，改仓库即时生效）
|
||
DSH_HOME="<your DSH_HOME>" ./install-skills.sh --agent dsh --link
|
||
|
||
# 远程/其他机器
|
||
./install-skills.sh --agent codex
|
||
|
||
# 看谁落后了
|
||
./install-skills.sh --agent codex --audit
|
||
```
|
||
|
||
`beta` 技能默认不装：需要时加 `--include-beta`。`promoted/beta/deprecated` 见 `SCOPE.md`。
|