skills-profile

按 Profile 批量管理 Agent Skills 的命令行工具。

skills-profile 是 npx skills 的薄封装层，让你可以通过配置文件（Profile）一次性安装、卸载或更新一组 skills，而不需要逐个手动敲命令。

快速开始

1. 初始化全局配置文件

创建 ~/.agents/skills-profile.yml：

agents: [claude-code]

profiles:
  coding:
    description: Coding skills from tw93
    skills:
      - repo: tw93/Waza
        names: [check, design]

  solopreneur:
    description: Solopreneur framework from slavingia
    skills:
      - repo: slavingia/skills

2. 在项目里安装一个 Profile

npx skills-profile install coding

第一次运行时，如果项目下没有 .agents/skills-profile.yml，工具会自动创建一个空白配置文件，方便你后续做本地覆盖。

3. 全局安装（不绑定到项目）

npx skills-profile install coding --global

加上 --global 时，工具会：

• 只读取全局配置文件 ~/.agents/skills-profile.yml
• 将 skills 安装到全局作用域（~/.agents/skills/ 和 ~/.claude/skills/）
• 不在当前目录创建项目级配置文件

这在多个项目共用同一套 skills 时很有用，避免每个项目重复安装。

4. 卸载 Profile

npx skills-profile uninstall coding

卸载同样支持 --global，用于移除全局安装的 skills：

npx skills-profile uninstall coding --global

5. 查看所有可用 Profiles

npx skills-profile list

加上 --global 只列出全局配置中的 profiles：

npx skills-profile list --global

6. 查看支持的 Agents

npx skills-profile agents

支持的命令

| 命令 | 别名 | 说明 | |------|------|------| | install <profile> | add | 安装指定 profile 下的所有 skills | | uninstall <profile> | remove | 卸载指定 profile 下的所有 skills | | list | — | 列出当前可用的所有 profiles | | agents | — | 列出底层 npx skills 支持的所有 agent 标识符 |

全局选项

| 选项 | 说明 | |------|------| | -g, --global | 使用全局配置文件，同时将技能安装/卸载到全局作用域（用户级，而非项目级） | | -a, --agent <agents...> | 指定目标 agent（如 claude-code、cursor），会与配置文件中的 agents 合并 | | -h, --help | 显示帮助 | | -v, --version | 显示版本 |

配置文件

位置

采用与 skills CLI 对齐的路径：

• 全局配置：~/.agents/skills-profile.yml
• 项目配置：<project-root>/.agents/skills-profile.yml

覆盖规则

读取配置时，同时加载全局和项目级配置：

• 若项目级配置中存在与全局同名的 profile，则完全覆盖全局该 profile 的所有字段（description、skills 等）。
• agents 字段也以项目级为准（覆盖全局）。

完整配置示例

# 默认目标 agent（可选）
agents: [claude-code, cursor]

profiles:
  coding:
    description: Coding skills
    skills:
      - repo: tw93/Waza
        names: [check, design]
      - repo: slavingia/skills

  writing:
    description: Writing assistant
    skills:
      - repo: user/writing-skills
      - repo: anthropic/skills
        names: [editor, reviewer]

  my-local:
    description: Local custom skills
    skills:
      - repo: ./my-skills/custom-tool
      - repo: ~/global-skills/shared-helper

字段说明

| 字段 | 类型 | 说明 | |------|------|------| | agents | string[] (可选) | 默认目标 agent 列表，命令行 -a 会与其合并 | | profiles | object | profile 集合，key 为 profile 名称 | | description | string (可选) | profile 简介，list 命令展示用 | | skills | array (可选) | 该 profile 下需要安装的 skill 列表 | | skills[].repo | string | 必填。远程仓库 owner/repo，或本地路径 ./xxx、~/xxx、/xxx | | skills[].names | string[] (可选) | 只安装/卸载该仓库/路径下的指定 skill names。若写空数组 []，则跳过该条目 |

卸载的工作原理

npx skills remove 需要传入 skill name 而非仓库地址。因此卸载时采用两层策略：

1. 第一层：如果配置中显式写了 names，直接用这些 names 去卸载。
2. 第二层：如果未写 names，则读取项目下的 skills-lock.json，根据 source 字段反查该 repo 对应安装了哪些 skill names，再进行卸载。

如果 skills-lock.json 缺失或无法匹配，工具会跳过该条目，并在最后输出友好提示，告知用户哪些 skill 未被处理以及建议的手动操作。

本地路径 Skill 的支持

你可以在 repo 中直接写本地路径：

skills:
  - repo: ./my-skills/custom-tool
  - repo: ~/global-skills/shared-helper

工具会自动将其解析为绝对路径后传给 npx skills add。安装前会校验路径是否存在，不存在则直接报错。

注意：底层 npx skills 对本地路径 skill 不支持 update 刷新，如需更新请直接重新执行 install <profile>。

更新 Skill

当前版本不单独提供 update 命令。如需更新某个 profile 下的 skills，直接重新执行：

npx skills-profile install <profile>

底层 npx skills add 对已安装的 skill 会重新覆盖/同步到最新状态。

配置约束与边界

• description 选填，缺失时 list 显示 -。
• skills 选填，缺失或为空数组 [] 时视为无操作。
• skills[].repo 必填，格式非法或本地路径不存在时报错。
• names 中的重复项会自动去重。
• 如果全局和项目级配置都缺失，运行命令会报错。
• 如果指定的 profile 不存在，会报错并提示当前可用的 profiles。

License

MIT