首页 > 专题 > AI开源项目 > 文章详情
返回 AI开源项目

aweskill 使用手册：AI Agent Skill 包管理器（v0.3.3，47 个 Agent 支持）

2026年05月17日 50 阅读 AI开源项目

版本：0.3.3 | Node ≥ 20 | MPL-2.0 | 支持 47 个 AI Agent（macOS / Windows）

官网： https://aweskill.webioinfo.top
GitHub： https://github.com/mugpeng/aweskill

一、这是什么，解决什么问题

1.1 背景痛点

当你同时使用多个 AI 编码工具时——比如 Claude Code 做深度重构、Cursor 做快速编辑、Codex 跑自主任务、Gemini CLI 做多模态——每个工具都有自己存放 SKILL.md 的目录。很快你会遇到：

  • 每个工具的 skill 散落在各自目录，互不同步
  • 同一个 skill 复制了 N 份，时间一久不知道哪份是最新
  • 本地修改了某个 skill，但忘了同步到其他工具
  • 重装工具或换电脑后，skill 全丢了

1.2 aweskill 是什么

aweskill 是一个本地 Skill 包管理器，设计思路类似 npm 管理代码包。它：

  1. 中央仓库：~/.aweskill/skills/ 存放所有 skill 的唯一正本，一份就够
  2. 多 Agent 投影：通过 symlink（macOS/Linux）或 junction/copy（Windows），把 skill 按需投射到任意多个 Agent 的目录
  3. Bundle 打包：按工作流（backend / frontend / daily-coding）分组，一次投影整组
  4. 来源追踪更新：记录每个 skill 的上游来源，一键拉取更新，同时保护本地修改
  5. Doctor 维护：修复损坏的投影、重复的 skill、异常的 frontmatter，保持本地状态健康
  6. 内置元技能：让 Agent 能通过自然语言调用 aweskill，自己管理自己的 skills

1.3 核心术语

| 术语 | 含义 |
|------|------|
| Central Store（中央仓库） | ~/.aweskill/skills/，所有 skill 的唯一正本 |
| Projection（投影） | 把中央仓库中的 skill 按需链接到某个 Agent 的 skill 目录 |
| Bundle（捆绑包） | 一组 skill 的命名集合，按项目/团队/工作流组织 |
| Symlink / Junction | 投影的技术手段，macOS/Linux 用 symlink，Windows 用 junction |
| Source Tracking（来源追踪） | 记录 skill 上游来源，支持 aweskill update 拉取更新 |
| Doctor | 一组修复和维护命令，处理投影损坏、重复、frontmatter 异常等 |

二、安装

2.1 环境要求

  • Node.js ≥ 20（运行 node --version 确认）
  • npm（随 Node.js 自带）
  • macOS 或 Windows（本文以 macOS 为默认，Windows 差异会注明）

2.2 方式一：npm 安装（推荐）

# 全局安装
npm install -g aweskill

# 确认版本
aweskill --version   # 0.3.3

# 查看帮助
aweskill --help

2.3 方式二：固定版本

npm install -g aweskill@0.3.3

2.4 方式三：让 AI Agent 自己安装

如果你已经在某个 AI 编码 Agent（Claude Code / Codex / Cursor / Gemini CLI 等）里工作，直接粘贴：

Read https://github.com/mugpeng/aweskill/blob/main/README.ai.md and follow it to install aweskill.

Agent 会自动完成：安装 CLI → 初始化中央仓库 → 投影内置管理 skill → 提示你重启。

2.5 方式四：GitHub 开发版

# 安装 GitHub dev 分支（可能不稳定）
npm install -g mugpeng/aweskill#dev

# 自更新
aweskill self-update --dev

三、初始化

安装完成后，只需做一次初始化：

# 创建 ~/.aweskill 目录结构
aweskill store init

# 确认仓库位置
aweskill store where --verbose

正常输出示例：

aweskill home: ~/.aweskill
central store: ~/.aweskill/skills/
bundles:       ~/.aweskill/bundles/
backup:        ~/.aweskill/backup/

注意：store init 只需要执行一次。之后即使添加新的 Agent 或新的 skill，都不需要重新 init。

四、核心操作流程

4.1 流程概览

┌────────────────────  ──────┐
│                    日常工作流                                                          │
│                                                                                                │
│  查找 skill ──► 安装到中央仓库 ──► 投影到 Agent        │
│       │                                    │                                              │
│       └──── 更新来源 ─────── ────┘           │
│                                                                                                 │
│  维护命令（doctor）：同步、清理、去重、修复 frontmatter │
└───────────────────────────┘

4.2 查找 skill

# 搜索远程 registry（skills.sh + sciskillhub）
aweskill find <关键词>

# 示例
aweskill find python data analysis
aweskill find pr review

# 只搜索本地中央仓库
aweskill find review --local

# 限定单个 provider
aweskill find protein --provider sciskill
aweskill find python --provider skills-sh

# 限制每 provider 返回数量
aweskill find python --limit 5

aweskill find 会同时搜索 skills.sh（社区 skill）和 sciskillhub.org（科研技术类 skill），返回可直接安装的 source 地址。

4.3 安装 skill 到中央仓库

# 从 GitHub 风格来源安装
aweskill store install owner/repo

# 从 sciskillhub 安装（格式：sciskill:<category/tags/name>）
aweskill store install sciskill:open-source/research/lifesciences-proteomics

# 从本地路径安装
aweskill store install /path/to/my-skill

# 安装时指定名称
aweskill store install owner/repo --as my-custom-name

# 覆盖已存在的 skill
aweskill store install owner/repo --override

安装后 skill 进入 ~/.aweskill/skills/，被 aweskill 追踪管理。

4.4 追踪更新

# 检查所有已追踪 skill 是否有上游更新（不实际修改）
aweskill store update --check

# 刷新某个 skill
aweskill store update my-skill-name

# 从指定来源更新
aweskill store update my-skill --source owner/repo

重要原则：更新时，中央仓库中的副本被视为受保护的本地状态。如果你在中央仓库里手动改过 skill 内容，aweskill update 不会覆盖你的本地修改。

4.5 查看中央仓库

# 列出所有已安装 skill
aweskill store list
aweskill store list --verbose   # 显示详情

# 查看某个 skill 的摘要
aweskill store show my-skill

# 输出完整 SKILL.md 内容
aweskill store show my-skill --raw

# 只输出 skill 路径
aweskill store show my-skill --path

# 从中央仓库删除 skill
aweskill store remove my-skill --force

五、投影 skill 到 Agent

5.1 支持的 Agent（47 个）

主要列表：

| Agent ID | 对应工具 |
|----------|----------|
| claude-code | Claude Code（CLI 或 IDE 插件） |
| codex | OpenAI Codex CLI |
| cursor | Cursor |
| windsurf | Windsurf |
| gemini-cli | Gemini CLI |
| qwen-code | Qwen Code（通义灵码） |
| opencode | OpenCode |
| continue | Continue |
| trae / trae-cn | Trae |
| kimi-cli | Kimi CLI |
| warp | Warp AI |
| goose | Goose |
| replit | Replit |

完整列表（47 个）：adal, amp, antigravity, augment, bob, claude-code, cline, codebuddy, command-code, continue, codex, copilot, cortex, crush, cursor, deepagents, droid, firebender, gemini-cli, github-copilot, goose, iflow-cli, junie, kilo, kilo-code, kimi-cli, kiro-cli, kode, mcpjam, mistral-vobe, mux, neovate, openclaw, openclaude-ide, openhands, opencode, pi, pochi, qoder, qwen-code, replit, roo, trae, trae-cn, warp, windsurf, zencoder

5.2 找到当前使用的 Agent

aweskill agent supported

输出中带 ✓ 的是检测到的已安装 Agent，带 x 的是未检测到。找到对应的那一行，确认 Agent ID。

5.3 投影内置管理 skill（首次必做）

必须做：先把 aweskill 和 aweskill-doctor 这两个内置 skill 投影到当前 Agent，这样 Agent 之后才能通过自然语言调用 aweskill。

# 把两个元 skill 投影到指定 Agent
aweskill agent add skill aweskill,aweskill-doctor --global --agent <你的-agent-id>

# 示例（以 Claude Code 为例）
aweskill agent add skill aweskill,aweskill-doctor --global --agent claude-code

5.4 验证投影状态

aweskill agent list --global --agent claude-code

正常输出中，aweskill 和 aweskill-doctor 应显示为 linked。

5.5 投影任意 skill 到 Agent

# 把一个 skill 投影到检测到的全局 Agent 目录
aweskill agent add skill my-skill

# 把多个 skill 投影到指定 Agent
aweskill agent add skill skill-a,skill-b --global --agent codex

# 把整个 bundle 投影到指定 Agent
aweskill agent add bundle backend --global --agent claude-code

# 把 bundle 投影到所有检测到的 Agent
aweskill agent add bundle backend --global --agent all

5.6 删除投影

# 删除某个 skill 的投影（不删除中央仓库副本）
aweskill agent remove skill my-skill --global --agent claude-code

# 强制删除
aweskill agent remove skill my-skill --global --agent claude-code --force

5.7 恢复投影（recover）

如果想把托管 symlink 恢复为完整目录（取消投影关系）：

aweskill agent recover --global --agent claude-code

六、Bundle 管理

Bundle 用来把多个相关 skill 打成一个包，一次投影到多个 Agent。

6.1 创建 Bundle

# 创建一个空的 bundle
aweskill bundle create backend

# 查看所有 bundle
aweskill bundle list
aweskill bundle list --verbose

6.2 向 Bundle 添加 skill

# 添加一个或多个 skill 到 bundle
aweskill bundle add backend api-design,db-schema,auth

# 查看 bundle 内容
aweskill bundle show backend

6.3 从 Bundle 移除 skill

aweskill bundle remove backend db-schema

6.4 使用 Bundle 模板

# 列出内置模板
aweskill bundle template list --verbose

# 导入一个模板到本地 bundle
aweskill bundle template import my-template

6.5 实际使用场景

假设你有一个 frontend bundle 包含 react-best-practices、css-architecture、testing-patterns 三个 skill：

# 创建 bundle
aweskill bundle create frontend
aweskill bundle add frontend react-best-practices,css-architecture,testing-patterns

# 一次性投影到 Cursor 和 Windsurf
aweskill agent add bundle frontend --global --agent cursor
aweskill agent add bundle frontend --global --agent windsurf

# 或者投影到所有 Agent
aweskill agent add bundle frontend --global --agent all

七、维护：Doctor 系列命令

所有 doctor 命令默认 dry-run（只显示要做什么，不实际修改）。加上 --apply 才会真正执行。

7.1 doctor sync — 同步和修复 Agent 投影

检查并修复 Agent 目录中的：broken（损坏链接）、duplicate（重复）、matched（匹配）、new（新增）、suspicious（可疑）条目。

# 先预览，不修改
aweskill doctor sync --global --agent claude-code

# 执行修复
aweskill doctor sync --global --agent claude-code --apply

# 额外删除 suspicious 条目
aweskill doctor sync --global --agent claude-code --apply --remove-suspicious

7.2 doctor clean — 清理中央仓库可疑条目

在中央仓库中查找不符合规范的文件和目录：

# 预览可疑条目
aweskill doctor clean

# 执行清理
aweskill doctor clean --apply

# 只处理 skill，不处理 bundle
aweskill doctor clean --apply --skills-only

7.3 doctor dedup — 去重

把中央仓库中重复的 skill 移动到 ~/.aweskill/dup_skills/：

# 预览重复项
aweskill doctor dedup

# 执行去重
aweskill doctor dedup --apply

# 去重前先备份
aweskill doctor dedup --apply --backup

# 直接删除（不备份）
aweskill doctor dedup --apply --delete

7.4 doctor fix-skills — 修复 SKILL.md frontmatter

检查并自动修复以下问题：

| 类别 | 问题 | 修复方式 |
|------|------|----------|
| missing-closing-delimiter | frontmatter 未闭合 | 补上 --- 结束标记 |
| invalid-yaml | frontmatter YAML 格式损坏 | 重建 frontmatter |
| added-frontmatter | 文件无 frontmatter | 插入最小 frontmatter |
| normalized-name | name 字段格式错误 | 恢复规范名称 |
| normalized-description | description 缺失 | 从正文第一句恢复描述 |

--include-info 时还会报告信息类检查（不修改）：normalized-required-permissions、preserved-unknown-fields、removed-empty-fields。

# 预览 frontmatter 问题
aweskill doctor fix-skills

# 修复前先备份原文件
aweskill doctor fix-skills --apply --backup

# 执行修复（只写真修复项，不写信息项）
aweskill doctor fix-skills --apply

# 也输出信息项
aweskill doctor fix-skills --apply --include-info

备份文件位置：~/.aweskill/backup/fix_skills/

八、备份和恢复

8.1 备份

# 备份整个中央仓库（skills + bundles），输出 tar.gz
aweskill store backup

# 指定备份文件路径
aweskill store backup ~/Downloads/aweskill-backup-20250512.tar.gz

# 只备份 skill，不备份 bundle
aweskill store backup --skills-only

8.2 恢复

# 从备份文件恢复（--override 覆盖已有）
aweskill store restore ~/Downloads/aweskill-backup-20250512.tar.gz --override

# 从已解压的备份目录恢复
aweskill store restore ~/Downloads/aweskill-backup/ --override

# 只恢复 skill
aweskill store restore ~/Downloads/aweskill-backup.tar.gz --override --skills-only

九、导入和迁移

9.1 从现有 Agent 目录导入

如果你已经有其他 Agent 管理的一堆 skill，想统一收入 aweskill 中央仓库：

# 扫描检测到的 Agent skill 目录
aweskill store scan

# 扫描并导入到中央仓库（默认把原 Agent 目录转为 aweskill 托管投影）
aweskill store scan --import

# 扫描并导入，但保留原 Agent 目录不变
aweskill store scan --import --keep-source

9.2 导入外部 skill 目录

# 导入一个 skill 目录，保留原目录不变
aweskill store import ~/Downloads/pr-review

# 导入后把原目录替换为 aweskill 托管投影
aweskill store import ~/Downloads/pr-review --link-source

# 导入并为后续 store update 建立来源追踪
aweskill store import ~/Downloads/pr-review --track-source

# 导入整个 skills 根目录
aweskill store import ~/.agents/skills

9.3 更新 aweskill 自身

# 检查版本
aweskill self-update --check

# 从 npm 更新到稳定版
aweskill self-update

# 从 GitHub dev 分支更新（可能不稳定）
aweskill self-update --dev

十、内置管理 skill 详解

aweskill 内置了两个元 skill，安装后可以让 Agent 自己操作 aweskill：

10.1 aweskill skill

用途：日常操作（find、install、update、bundle、agent add）

当你对 Agent 说这些话时，Agent 会自动路由到对应命令：

| Agent 说的话 | 实际执行 |
|------------|---------|
| "帮我找一个 Python 数据分析 skill" | aweskill find python data analysis |
| "安装这个 skill 到 aweskill" | aweskill store install <source> |
| "检查哪些 skill 有更新" | aweskill store update --check |
| "把 skill X 投影到 Codex" | aweskill agent add skill X --global --agent codex |
| "创建一个 frontend bundle" | aweskill bundle create frontend |

10.2 aweskill-doctor skill

用途：修复和维护

| Agent 说的话 | 实际执行 |
|------------|---------|
| "检查 Codex 投影有没有问题" | aweskill doctor sync --global --agent claude-code |
| "清理中央仓库的可疑文件" | aweskill doctor clean --apply |
| "帮我去重，备份一下" | aweskill doctor dedup --apply --backup |
| "修复所有 SKILL.md 的 frontmatter 问题" | aweskill doctor fix-skills --apply --backup |

10.3 触发方式

内置 skill 通过标准 frontmatter 触发词激活，例如：

aweskill skill  技能管理  导入技能  投影技能  bundle  agent  aweskill  高级技能管理  recover  技能迁移
aweskill-doctor skill  技能有问题  skill 出错了  重复 skill  doctor  同步  修复 skill  清理  维护

Agent 读到这些触发词后，会自动调用对应 skill 的指引来执行任务。

十一、目录结构总览

~/.aweskill/
├── skills/                    # 中央仓库（所有 skill 的正本）
│   ├── my-skill/
│   │   └── SKILL.md
│   └── another-skill/
│       └── SKILL.md
├── bundles/                   # bundle 定义文件
│   └── backend.yaml
├── dup_skills/                # 去重暂存区（doctor dedup 移动至此）
├── backup/                    # 备份根目录
│   ├── dedup/                 # dedup 备份
│   └── fix_skills/            # fix-skills 备份
└── skills-lock.json           # 来源追踪记录（不要手动编辑）

十二、常见问题

Q1：投影后 Agent 看不到 skill？

  1. 确认投影成功：aweskill agent list --global --agent <id>
  2. 确认状态是 linked 而非 broken
  3. 重启 Agent（大多数 Agent 需要重启才能加载新 skill）
  4. 如果还是 broken，运行：aweskill doctor sync --global --agent <id> --apply

Q2：Windows 上 symlink 失败？

Windows 默认不允许普通用户创建 symlink。aweskill 会自动回退到 junction（目录联接）或受管 copy。如果遇到权限问题，尝试用 PowerShell 以管理员身份运行，或在 Windows 设置中启用开发者模式。

Q3：如何更新 aweskill 自身？

aweskill self-update           # npm 稳定版
aweskill self-update --dev     # GitHub dev 分支
aweskill self-update --check   # 只查版本，不更新

Q4：修改了中央仓库的 skill，想撤消？

用备份恢复：

aweskill store restore ~/.aweskill/backup/aweskill-backup-xxx.tar.gz --override

Q5：想把 skill 从某个 Agent 移除但不删中央仓库副本？

aweskill agent remove skill <skill-name> --global --agent <agent-id>

Q6：如何查看所有支持的 Agent？

aweskill agent supported

Q7：bundle 和直接投影多个 skill 有什么区别？

bundle 是一次性管理一组 skill 的单位。当你需要「这一组 skill 每次新机器都要装」或者「前端开发者的 skill 组合和后端不同」，用 bundle 更方便。直接 agent add skill 适合临时性、一次性的投影。

Q8：skills-lock.json 是什么？

~/.aweskill/skills-lock.json 是来源追踪数据库，记录每个 skill 的安装来源（GitHub 地址、sciskill ID 等）。不要手动编辑。aweskill store update 依赖这个文件知道从哪里拉取更新。

十三、命令速查表

安装 & 初始化

npm install -g aweskill          # 安装
aweskill store init              # 初始化中央仓库（只做一次）
aweskill self-update             # 更新 aweskill 自身
aweskill self-update --check     # 检查版本

查找 & 安装

aweskill find <关键词>            # 搜索远程 registry
aweskill find <关键词> --local    # 只搜本地
aweskill install <source>        # 安装到中央仓库
aweskill store update --check    # 检查来源更新
aweskill store update <skill>    # 更新某个 skill

中央仓库管理

aweskill store list              # 列出所有 skill
aweskill store show <skill>     # 查看 skill 内容
aweskill store remove <skill>   # 删除 skill
aweskill store backup            # 备份
aweskill store restore <file>   # 恢复

导入 & 扫描

aweskill store scan              # 扫描 Agent 目录
aweskill store scan --import    # 扫描并导入
aweskill store import <path>    # 导入本地路径

Bundle

aweskill bundle create <name>    # 创建 bundle
aweskill bundle add <bundle> <skill>   # 添加 skill
aweskill bundle show <bundle>    # 查看内容
aweskill bundle remove <bundle> <skill> # 移除

投影

aweskill agent supported         # 查看支持的 Agent
aweskill agent add skill <skills> --global --agent <id>   # 投影 skill
aweskill agent add bundle <bundle> --global --agent <id>  # 投影 bundle
aweskill agent remove skill <skill> --global --agent <id> # 移除投影
aweskill agent list             # 查看投影状态
aweskill agent recover          # 恢复为完整目录

Doctor 维护

aweskill doctor sync --global --agent <id>           # 预览同步
aweskill doctor sync --global --agent <id> --apply  # 执行同步
aweskill doctor clean                               # 预览清理
aweskill doctor clean --apply                       # 执行清理
aweskill doctor dedup                               # 预览去重
aweskill doctor dedup --apply --backup              # 执行去重并备份
aweskill doctor fix-skills                          # 预览修复
aweskill doctor fix-skills --apply --backup        # 执行修复并备份

十四、参考资料

  • 官网（含安装指南和兼容性总览）：https://aweskill.webioinfo.top
  • GitHub 仓库：https://github.com/mugpeng/aweskill
  • npm 包：https://www.npmjs.com/package/aweskill
  • AI Agent 安装说明：https://github.com/mugpeng/aweskill/blob/main/README.ai.md
  • skills.sh（社区 skill 发现）：https://skills.sh/
  • sciskillhub（科研技术类 registry）：https://sciskillhub.org/
教程