概览与快速上手

项目定位与目标

skills 是开放 Agent Skills 生态的官方命令行工具，用于在各类 AI 编码代理（Claude Code、Codex、Cursor、Gemini CLI 等 50+ 终端）之间发现、安装、同步与发布 SKILL.md 技能包。AGENTS.md 明确说明：skills 是 "the CLI for the open agent skills ecosystem"。资料来源：AGENTS.md

仓库的 package.json 仅声明两个运行时依赖（yaml 用于解析 frontmatter，其它内置），并通过 packageManager: [email protected] 与 engines.node: >=18 锁定环境。keywords 字段罗列了所有被识别的代理名称，可作为生态覆盖面的索引。资料来源：package.json

核心命令

根据 AGENTS.md 中的命令表，CLI 暴露的子命令如下表所示（节选高频项）：

skills a 等价于 add；skills i / skills install（无参）等价于 experimental_install。资料来源：AGENTS.md

快速开始

最简安装方式为通过 npx 调用，并支持 owner/repo、完整 URL、GitLab 链接、本地路径与任意 Git URL。README.md 给出了典型用法：

# 安装 vercel-labs/agent-skills 全部技能到当前项目的所有代理
npx skills add vercel-labs/agent-skills

# 直接定位到仓库中的某个技能目录
npx skills add https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines

# 安装到全局用户目录，并指定代理
npx skills add owner/repo -g -a claude-code -a codex

常用选项包括 -g, --global（用户级安装）、-a, --agent <agents...>（多代理目标）、-s, --skill <skills...>（多技能筛选，'*' 表示全部）、-l, --list（仅列出不安装）、--copy（拷贝而非软链接）、-y, --yes（跳过确认）以及 --all（无提示全量安装）。资料来源：README.md

技能发现与代理支持

README.md 列出了仓库内的技能发现路径：skills/、skills/.curated/、skills/.experimental/、skills/.system/、以及 30+ 形如 .agents/skills/、.claude/skills/、.codex/skills/ 的代理专属目录；SKILL.md 在浅层会"遮蔽"其下嵌套的同名技能，可用 --full-depth 进一步发现 examples/、tests/ 等位置的技能。资料来源：README.md

src/blob.ts 中的 PRIORITY_DIRS 常量与上述列表一一对应，是程序化发现的实现依据；该文件还定义了 BlobSkill、SkillDownloadResponse 等类型，描述"快照下载"路径——skills.sh/api/download 会在远端预拉取 SKILL.md 与 frontmatter，再回灌到本地，从而避免完整 git clone。资料来源：src/blob.ts

支持的代理枚举集中在 src/types.ts 的 AgentType 联合类型中（约 60+ 名称），包含 'claude-code'、'codex'、'cursor'、'gemini-cli'、'kimi-code-cli'、'antigravity-cli'、'openclaw'、'zed' 等；AgentConfig 接口统一描述每个代理的 skillsDir、globalSkillsDir 与 detectInstalled 函数，便于扩展。资料来源：src/types.ts

架构与数据流

CLI 入口 src/cli.ts 负责命令路由、init、check、update 等顶层逻辑；src/add.ts 实现安装核心；src/source-parser.ts 的 parseSource 解析用户输入，返回 { type: 'github' | 'gitlab' | 'git' | 'well-known' | 'local', url, ref?, subpath? } 等结果。isWellKnownUrl 会排除 github.com、gitlab.com、raw.githubusercontent.com 与以 .git 结尾的 URL，将剩余 HTTP(S) 视为 well-known 来源——这是 /.well-known/agent-skills/index.json（v0.1）与 /.well-known/skills/index.json（v0.2）发现协议的入口。资料来源：src/source-parser.ts、src/providers/wellknown.ts

flowchart LR
  A[用户输入 source] --> B[parseSource]
  B -->|github/gitlab/git| C[git clone / Trees API]
  B -->|well-known| D[RFC 8615 index.json]
  B -->|local| E[直接读取 SKILL.md]
  C --> F[findSkillMdPaths / blob 快照]
  D --> F
  E --> F
  F --> G[frontmatter 解析与 sanitize]
  G --> H[写入代理 skillsDir 或 .agents/skills]
  H --> I[更新 skills-lock.json]

src/use.ts 中的 materializeUseSkill 将技能临时物化到 os.tmpdir()，并通过 isPathSafe 防止路径穿越，区分 blob（来自快照）、well-known（来自索引）与本地目录三种来源。资料来源：src/use.ts

更新与锁文件

AGENTS.md 描述了 skills check / skills update 的工作流：读取 ~/.agents/.skill-lock.json（v3，键为 skillFolderHash）→ 调用 GitHub Trees API（/git/trees/<branch>?recursive=1，先 main 后 master）→ 与本地哈希比较 → 不一致时通过 node <repo>/bin/cli.mjs add <source-tree-url> -g -y 触发重装，以避免嵌套 npx。src/update-source.test.ts 验证了 buildUpdateInstallSource 与 formatSourceInput 在拼接 #ref 片段、嵌套子路径时的行为。资料来源：AGENTS.md、src/update-source.test.ts

常见使用陷阱（来自社区反馈）

• 参数未校验：skills update --dry-run -g 不会报错，提示子命令需要严格参数校验。资料来源：Issue #1393
• Claude Code 路径不匹配：安装默认落到 ~/.agents/skills/，而 Claude Code 实际读取 ~/.claude/skills/，需在交互提示中切换代理。资料来源：Issue #1385
• Windows 上 skills list -g 较慢：当全局代理目录数量多时存在性能瓶颈。资料来源：Issue #1389
• 缺少 install / sync 还原命令：skills-lock.json 存在但无 npm ci 风格的恢复命令，团队级复现受限。资料来源：Issues #283、#549

See Also

• 命令参考与选项：README.md
• 代理与类型定义：src/types.ts
• 源码解析与发现协议：src/source-parser.ts、src/providers/wellknown.ts
• 临时物化与使用流：src/use.ts
• 内置 find-skills 元技能说明：skills/find-skills/SKILL.md

总体架构

CLI 的入口位于 src/cli.ts，负责命令路由、banner 输出、init / check / update 等顶层分发；每个子命令由独立的模块实现：

src/
├── cli.ts         # 入口与命令路由
├── add.ts         # 核心 add 逻辑
├── use.ts         # use 解析与 Agent 启动
├── list.ts        # 列出已安装技能
├── find.ts        # find 搜索命令
├── update.ts      # 更新已安装技能
├── remove.ts      # 移除技能
├── sync.ts        # 从 node_modules 同步
├── source-parser.ts # Git/URL/本地路径解析
├── skill-lock.ts  # 全局锁文件 (~/.agents/.skill-lock.json)
└── local-lock.ts  # 项目级锁文件 (skills-lock.json)

资料来源：AGENTS.md:11-13、AGENTS.md:39-60

核心命令

下表汇总了 CLI 的所有顶层命令及其作用，命令别名与详细说明见各小节。

资料来源：AGENTS.md:11-18

`skills add` — 安装技能

支持多种来源格式（GitHub 简写、完整 URL、GitLab、任意 Git URL、本地路径），源解析逻辑位于 src/source-parser.ts，可识别 GitHub、GitLab、自定义域、SSH 与端口号。--agent / -a 用于指定目标 Agent；-g / --global 安装到 ~/.agents/skills/ 等全局目录；--skill / -s 选择仓库内单个技能；--yes / -y 跳过交互；--all 安装全部发现的技能。资料来源：src/source-parser.ts:1-87、src/source-parser.test.ts:6-31

`skills use` — 临时使用单个技能

use 会以与 add 相同的方式解析来源，将所选技能文件写入临时目录；不带 --agent 时仅将生成的 prompt 打印到 stdout，带 --agent 时会按 src/use.ts 中维护的 USE_AGENT_CONFIGS（目前支持 claude-code 与 codex）启动相应 Agent。可选 --full-depth 启用更深的目录扫描，--skill / -s 指定技能名，--dangerouslyAcceptOpenclawRisks 接受 openclaw 相关风险。资料来源：src/use.ts:3-13

`skills list` / `ls` — 列出已安装技能

全局模式下遍历各 Agent 的全局目录；项目级模式扫描当前工作目录的 .agents/skills/ 等约定位置。注意：在 Windows 平台上，多个全局 Agent 技能目录会导致 skills list -g 性能显著下降（参见社区 issue #1389）。资料来源：src/list.ts、社区 issue #1389

`skills find` — 搜索技能

提供基于关键词的技能搜索能力，方便在不直接知道仓库名时定位可安装的技能。内置 find-skills 技能（位于 skills/find-skills/SKILL.md）给出了检索建议，例如优先尝试 vercel-labs/agent-skills 与 ComposioHQ/awesome-claude-skills 等流行来源。资料来源：skills/find-skills/SKILL.md:30-37

`skills update [skills...]` — 更新技能

可指定具体技能名进行定向更新，也可在不传参时扫描所有已安装技能；项目级与全局级会分别处理（v1.5.0 改进）。已知问题：子命令参数校验不完善（参见 issue #1393），例如 pnpx skills update --dry-run -g 不会因 --dry-run 不被识别而报错。

`skills remove` — 移除技能

删除本地已安装的技能；与 skill-lock.ts 维护的全局锁文件以及 local-lock.ts 维护的 skills-lock.json 保持同步，确保后续 update 不会尝试恢复已删除项。资料来源：src/remove.ts

实验性命令与锁文件

skills experimental_install（别名 i / install，无参数）等价于 npm ci：从 skills-lock.json 还原项目级安装。社区长期呼吁的 skills install / skills sync 命令目前仍标记为 experimental（参见 issue #283 与 #549）。需要注意的现存问题：

• 项目级安装默认不会被 skills-lock.json 追踪（issue #155），需结合全局 ~/.agents/.skill-lock.json 一起管理。
• 锁文件仅跟踪全局安装条目，generate-lock 不扫描项目级目录。

资料来源：src/sync.ts、src/skill-lock.ts、src/local-lock.ts、issue #155

源格式参考

add / use 共用同一套源解析器（src/source-parser.ts），典型用法包括：

# GitHub 简写
npx skills add vercel-labs/agent-skills

# 完整 URL
npx skills add https://github.com/vercel-labs/agent-skills

# 直接指向仓库内某个技能
npx skills add https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines

# GitLab（含子组、自定义域、端口）
npx skills add https://git.corp.com:8443/group/subgroup/project/-/tree/main/src

# 任意 Git URL / SSH
npx skills add [email protected]:owner/repo.git

常见陷阱与兼容性说明

• Claude Code 路径差异：在 Claude Code 中，运行 /skill-name 前请确认技能已被安装到 ~/.claude/skills/ 而非 ~/.agents/skills/，否则会报 "Unknown skill"（issue #1385）。
• Openclaw 风险：自 v1.4.9 起 CLI 会针对 openclaw 发出警告，因该生态出现重复与恶意技能（v1.4.9 发行说明）。
• 依赖 Node ≥ 18：安装脚本需 Node.js 18 及以上版本。资料来源：package.json:engines

参见

• 见 README.md 了解完整使用说明与支持 Agent 列表
• 见 AGENTS.md 了解代码库内部架构与命令入口
• 见 src/source-parser.ts 了解源 URL 解析规则的全部细节
• 见 src/providers/wellknown.ts 了解 RFC 8615 well-known 技能发现机制（v0.1.0 / v0.2.0）

总体架构

CLI 采用单入口 bin/cli.mjs + 子命令分发的结构。AGENTS.md 描述了源码目录组织：src/cli.ts 负责主入口与命令路由，src/add.ts 实现 add 核心逻辑，src/use.ts 实现 use 一次性使用流程，src/source-parser.ts 与 src/providers/wellknown.ts 负责源解析，src/blob.ts 提供基于 GitHub Trees API 的快速下载路径，src/types.ts 定义所有支持的 AgentType 枚举。

flowchart LR
  User[用户 npx skills] --> CLI[cli.ts 路由]
  CLI --> Add[add.ts]
  CLI --> Use[use.ts]
  CLI --> List[list.ts]
  CLI --> Update[update.ts]
  Add --> Parser[source-parser.ts]
  Parser --> Git[git 源]
  Parser --> WellKnown[providers/wellknown.ts]
  Parser --> Blob[blob.ts 快照下载]
  Add --> Installer[installer]
  Installer --> Agents[70+ AgentType 目录]
  Use --> TempDir[临时目录]
  Use --> AgentCLI[claude / codex 进程]

更新机制依赖 ~/.agents/.skill-lock.json 中记录的 skillFolderHash 与 GitHub Trees API 实时返回的目录 SHA 比较，不匹配即视为可更新。AGENTS.md 明确指出 skills update 通过 node <repo>/bin/cli.mjs add <source-tree-url> -g -y 直接复用当前 CLI 入口，避免嵌套 npx 行为带来的副作用。

资料来源：AGENTS.md

智能体兼容矩阵

src/types.ts 的 AgentType 联合类型列出了所有受支持的智能体，包括 claude-code、codex、cursor、opencode、gemini-cli、github-copilot、kimi-code-cli、antigravity 等。package.json 的 keywords 数组与之对应，可作为生态广度的元数据来源。

每个智能体都映射到一对目录：项目级 ./<agent>/skills/ 与全局 ~/<agent>/skills/。README.md 给出推荐用法——以符号链接（symlink）方式将单一规范副本连接到各智能体目录，便于更新；不支持符号链接的环境可改用 --copy 模式复制独立副本。少量"通用"智能体（如 Cline、Dexto、Kimi Code CLI、Loaf、Warp、Zed）共享 ~/.agents/skills/ 这条规范路径，由 v1.5.10 的"attribute canonical global skills to universal agents"修复保证列表归属正确。

资料来源：src/types.ts:1-80、README.md

源类型与解析流程

src/source-parser.ts 实现了多源归一化：GitHub 简写 owner/repo、完整 URL、tree 路径、GitLab URL、任意 git URL、本地路径都会被解析为 git 类型；非已知 git 主机的 HTTP(S) URL 则进入 well-known 流程。isWellKnownUrl() 显式排除 github.com、gitlab.com、raw.githubusercontent.com 以及 .git 结尾的链接，避免与 git 解析路径冲突。

well-known 解析支持 v1（/.well-known/agent-skills/index.json）与 v2（/.well-known/skills/index.json）两种协议，由 src/providers/wellknown.ts 中的 WellKnownIndexV1 / WellKnownIndexV2 类型表达；v2 引入 $schema、type（skill-md / archive）、url 与 digest 字段，从而支持带摘要校验的归档下载。src/blob.ts 则在 GitHub 源上额外提供 Trees API + raw 前置元数据 + skills.sh 缓存 blob 的三段式快速下载，回避完整 git clone 带来的带宽与时间开销。

src/use.ts 定义了 USE_AGENT_CONFIGS，目前仅 claude-code（命令 claude）与 codex 接入"一次性使用 + 启动智能体进程"模式；其它智能体只能安装到磁盘。--dangerously-accept-openclaw-risks 标志针对 v1.4.9 起加入的 OpenClaw 风险告警，使用前需用户显式确认。

资料来源：src/source-parser.ts、src/providers/wellknown.ts、src/blob.ts、src/use.ts

社区关注的兼容性问题

• 目录路径错配：issue #1385 报告 Claude Code 实际读取 ~/.claude/skills/ 而非 ~/.agents/skills/，需要确认目标智能体的实际加载路径，必要时使用 --copy 显式落到正确目录。
• Windows 性能问题：issue #1389 指出 skills list -g 在全局智能体目录数量多时极慢，可通过 --agent <name> 过滤（参见 README 中 npx skills ls -a claude-code 示例）减少遍历范围。
• 更新参数校验缺失：issue #1393 指出 skills update --dry-run 这样的未知 flag 不会报错，建议更新前先运行 skills check 查看可更新项。
• v1.5.10 修复的关键兼容项：包括 Antigravity CLI / Kimi Code CLI 等新智能体（#1345、#1347）、非简写源的子路径追加修正（#1344）以及 GitHub clone 失败时回退到 gh 与 ssh 认证（#1350）。

资料来源：README.md、AGENTS.md

See Also

• Skills 安装与源解析
• find-skills：技能发现工作流
• well-known 技能发现协议

锁文件、Sync 与已知问题

概述

skills CLI 通过锁文件（Lock File）记录已安装 skill 的来源、版本与内容哈希，从而在多台机器、多个 agent 之间复现一致的安装状态。锁文件体系分为全局锁（记录 ~/.agents/skills/ 下的安装）和项目级本地锁（skills-lock.json），二者职责不同、互不替代。配合 experimental_install（别名 install / i）与 experimental_sync 两个命令，CLI 尝试提供「类 npm ci」的还原体验——但当前实现仍处于实验阶段，存在若干已知的限制与社区反馈中的痛点。

AGENTS.md 中明确列出了与锁文件相关的命令入口：

资料来源：AGENTS.md

锁文件结构与本地锁写入流程

本地锁的实现集中在 src/local-lock.ts，它定义了 LocalSkillLockFile 数据结构（包含 version 字段与 skills 字典），并对外暴露读取、写入与哈希计算函数。读取时若 parsed.version < CURRENT_VERSION 会丢弃旧锁并返回空对象，从而保证向前兼容。

写入逻辑有两个关键设计：

1. 字典按键名字母序排序——保证生成的 JSON 在多次写入之间产生稳定的 diff。
2. computeSkillFolderHash——递归读取 skill 目录中所有文件，按相对路径排序后拼接并计算 SHA-256，用作内容指纹，资料来源：src/local-lock.ts:computeSkillFolderHash

// 示例：本地锁写入时的排序逻辑
const sortedSkills: Record<string, LocalSkillLockEntry> = {};
for (const key of Object.keys(lock.skills).sort()) {
  sortedSkills[key] = lock.skills[key]!;
}

资料来源：src/local-lock.ts:writeLocalLock

对于「非本地」来源，CLI 在解析源字符串时会提取 owner/repo（GitHub）或 group/subgroup/repo（GitLab）形式的标识，写入锁条目，便于跨机器定位。SSH 形式（git@host:owner/repo.git）与 ssh:// 形式的 URL 均在 src/source-parser.ts:getOwnerRepo 中得到处理。

Sync / Install 命令与来源快照

CLI 支持三种「远程来源」模型：传统的 git 仓库、可下载的 blob 快照、以及基于 RFC 8615 well-known URI 的发现协议。三者在锁文件中以不同字段表达：

flowchart LR
  A[skills add <pkg>] --> B{来源类型}
  B -- GitHub/GitLab 简写 --> C[git 仓库]
  B -- 含 fragment 或子路径 --> D[git ref/subpath]
  B -- 任意 HTTP URL --> E[well-known]
  C --> F[写入本地锁]
  D --> F
  E --> F
  F --> G[experimental_install 还原]
  F --> H[experimental_sync 注入 node_modules]

其中 blob 模型在 src/blob.ts 中实现：通过 https://skills.sh 的下载端点获取预构建快照（SkillDownloadResponse，含 files 数组与 hash），避免在客户端执行完整的 git clone——这与 v1.4.8 的 changelog "Direct download from snapshot rather than require full git clone" 一致。

experimental_sync 的工作流则是反向的：它从 node_modules 中发现已发布的 skill 包，并将它们复制到目标 agent 目录，从而把 npm 安装链路与 agent skill 链路打通，资料来源：AGENTS.md。

use <pkg>@<skill> 命令（即 src/use.ts 中的 runUse）将 skill 物化到临时目录，区分 blob / well-known / 普通磁盘目录三种 kind，并对路径遍历做了 isPathSafe 校验。

已知问题与社区反馈

下列问题均来自社区 issue 与 release notes，反映了锁文件与 sync 流程目前的真实状态：

最新版本 v1.5.10 已修复若干关键缺陷：回退到 gh/ssh 进行 GitHub 克隆鉴权（#1350）、skills list 将规范全局 skill 归属于 universal agents（#1348），以及修复 update 对非简写来源错误追加子路径的问题（#1344）。v1.5.7 引入 v2 well-known 协议并把 GitHub Token 的使用改为「仅在限流兜底时懒加载」（#1146），v1.5.8 则在 skills update 中清理上游已删除的 skill（#1218）。

建议与规避方案

• 项目级 lock：若需在 CI 中复现项目内的 skill 集合，请手动把项目级安装也登记到 skills-lock.json，因为默认行为下只有 -g 全局安装会被追踪，资料来源：#155。
• Claude Code 用户：执行 npx skills add 后需将产物同步到 ~/.claude/skills/，或显式指定 -a claude-code 让 CLI 直接写入正确目录，资料来源：#1385。
• 大仓库调试：使用 --list 在不写入文件系统的情况下预览远端仓库的 skill，资料来源：README.md。
• 审计刷新：当 skill 内容更新后，公开页面的 Snyk 审计结果可能滞后，需要向仓库发起 re-audit 请求，资料来源：#1273。

See Also

• 架构总览：README.md
• 命令索引与别名：AGENTS.md
• 源解析与 well-known 协议：src/source-parser.ts、src/providers/wellknown.ts
• Blob 快照下载：src/blob.ts
• 本地锁实现：src/local-lock.ts
• 类型定义：src/types.ts

Pitfall Log / 踩坑日志

项目：AceDataCloud/Skills

摘要：发现 24 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/AceDataCloud/Skills | host_targets=claude_code, claude, gemini_cli, cursor, codex, chatgpt

2. 配置坑 · 失败模式：configuration: sync: update from Docs (1a91fb8 docs: sync from PlatformBackend [automated])

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: sync: update from Docs (1a91fb8 docs: sync from PlatformBackend [automated])
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: sync: update from Docs (1a91fb8 docs: sync from PlatformBackend [automated])
• 证据：failure_mode_cluster:github_issue | https://github.com/AceDataCloud/Skills/issues/430 | sync: update from Docs (1a91fb8 docs: sync from PlatformBackend [automated])

3. 配置坑 · 失败模式：configuration: sync: update from Docs (2042c6c fix(docs): unblock Mintlify build — inline gemini cross-opera...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: sync: update from Docs (2042c6c fix(docs): unblock Mintlify build — inline gemini cross-operation $refs (#66))
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: sync: update from Docs (2042c6c fix(docs): unblock Mintlify build — inline gemini cross-operation $refs (#66))
• 证据：failure_mode_cluster:github_issue | https://github.com/AceDataCloud/Skills/issues/428 | sync: update from Docs (2042c6c fix(docs): unblock Mintlify build — inline gemini cross-operation $refs (#66))

4. 配置坑 · 失败模式：configuration: sync: update from Docs (658897d docs: sync from PlatformBackend [automated])

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: sync: update from Docs (658897d docs: sync from PlatformBackend [automated])
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: sync: update from Docs (658897d docs: sync from PlatformBackend [automated])
• 证据：failure_mode_cluster:github_issue | https://github.com/AceDataCloud/Skills/issues/446 | sync: update from Docs (658897d docs: sync from PlatformBackend [automated])

5. 配置坑 · 失败模式：configuration: v2026.621.6

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v2026.621.6
• 对用户的影响：Upgrade or migration may change expected behavior: v2026.621.6
• 证据：failure_mode_cluster:github_release | https://github.com/AceDataCloud/Skills/releases/tag/v2026.621.6 | v2026.621.6

6. 配置坑 · 失败模式：configuration: v2026.622.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v2026.622.0
• 对用户的影响：Upgrade or migration may change expected behavior: v2026.622.0
• 证据：failure_mode_cluster:github_release | https://github.com/AceDataCloud/Skills/releases/tag/v2026.622.0 | v2026.622.0

7. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/AceDataCloud/Skills | README/documentation is current enough for a first validation pass.

8. 运行坑 · 运行可能依赖外部服务

• 严重度：medium
• 证据强度：source_linked
• 发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。
• 对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。
• 证据：packet_text.keyword_scan | https://github.com/AceDataCloud/Skills | matched external service / cloud / webhook / database keyword

9. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/AceDataCloud/Skills | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/AceDataCloud/Skills | no_demo; severity=medium

11. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/AceDataCloud/Skills | no_demo; severity=medium

12. 安全/权限坑 · 来源证据：sync: update from Docs (1a91fb8 docs: sync from PlatformBackend [automated])

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：sync: update from Docs (1a91fb8 docs: sync from PlatformBackend [automated])
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/AceDataCloud/Skills/issues/430 | 来源类型 github_issue 暴露的待验证使用条件。

13. 安全/权限坑 · 来源证据：sync: update from Docs (2042c6c fix(docs): unblock Mintlify build — inline gemini cross-operation $refs (#66))

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：sync: update from Docs (2042c6c fix(docs): unblock Mintlify build — inline gemini cross-operation $refs (#66))
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/AceDataCloud/Skills/issues/428 | 来源类型 github_issue 暴露的待验证使用条件。

14. 安全/权限坑 · 来源证据：sync: update from Docs (658897d docs: sync from PlatformBackend [automated])

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：sync: update from Docs (658897d docs: sync from PlatformBackend [automated])
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/AceDataCloud/Skills/issues/446 | 来源类型 github_issue 暴露的待验证使用条件。

15. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/AceDataCloud/Skills | issue_or_pr_quality=unknown

16. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/AceDataCloud/Skills | release_recency=unknown

17. 维护坑 · 失败模式：maintenance: v2026.621.4

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v2026.621.4
• 对用户的影响：Upgrade or migration may change expected behavior: v2026.621.4
• 证据：failure_mode_cluster:github_release | https://github.com/AceDataCloud/Skills/releases/tag/v2026.621.4 | v2026.621.4

18. 维护坑 · 失败模式：maintenance: v2026.621.5

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v2026.621.5
• 对用户的影响：Upgrade or migration may change expected behavior: v2026.621.5
• 证据：failure_mode_cluster:github_release | https://github.com/AceDataCloud/Skills/releases/tag/v2026.621.5 | v2026.621.5

19. 维护坑 · 失败模式：maintenance: v2026.621.7

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v2026.621.7
• 对用户的影响：Upgrade or migration may change expected behavior: v2026.621.7
• 证据：failure_mode_cluster:github_release | https://github.com/AceDataCloud/Skills/releases/tag/v2026.621.7 | v2026.621.7

20. 维护坑 · 失败模式：maintenance: v2026.621.8

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v2026.621.8
• 对用户的影响：Upgrade or migration may change expected behavior: v2026.621.8
• 证据：failure_mode_cluster:github_release | https://github.com/AceDataCloud/Skills/releases/tag/v2026.621.8 | v2026.621.8

21. 维护坑 · 失败模式：maintenance: v2026.622.1

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v2026.622.1
• 对用户的影响：Upgrade or migration may change expected behavior: v2026.622.1
• 证据：failure_mode_cluster:github_release | https://github.com/AceDataCloud/Skills/releases/tag/v2026.622.1 | v2026.622.1

22. 维护坑 · 失败模式：maintenance: v2026.622.2

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v2026.622.2
• 对用户的影响：Upgrade or migration may change expected behavior: v2026.622.2
• 证据：failure_mode_cluster:github_release | https://github.com/AceDataCloud/Skills/releases/tag/v2026.622.2 | v2026.622.2

23. 维护坑 · 失败模式：maintenance: v2026.622.3

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v2026.622.3
• 对用户的影响：Upgrade or migration may change expected behavior: v2026.622.3
• 证据：failure_mode_cluster:github_release | https://github.com/AceDataCloud/Skills/releases/tag/v2026.622.3 | v2026.622.3

24. 维护坑 · 失败模式：maintenance: v2026.622.4

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v2026.622.4
• 对用户的影响：Upgrade or migration may change expected behavior: v2026.622.4
• 证据：failure_mode_cluster:github_release | https://github.com/AceDataCloud/Skills/releases/tag/v2026.622.4 | v2026.622.4