1实现原理 · 为什么它能做到

SKILL.md 本身只是一层「协议说明 + 输出规范」，真正的安装动作交给自带 bash 脚本；用户永远只输入同一条命令，脚本内部自动判断宿主类型与入口

skills/dbs-install-skill/SKILL.md

用户始终使用同一条命令。脚本自动选择公共入口或专属入口，用户无需判断宿主类型，也无需添加模式参数。

这是「文档即接口」的设计：SKILL.md 负责让模型知道脚本存在与怎么调，脚本负责全部确定性逻辑，避免模型临场重写安装命令。

路由策略是「一个公共入口优先」：所有 Skill 都先链接到 ~/.agents/skills，只有仍未采用该约定的宿主才补专属目录，且必须其主目录已存在才创建

skills/dbs-install-skill/SKILL.md

以下客户端当前仍使用专属目录。只有对应主目录已经存在时，脚本才创建链接：

避免为没装的客户端凭空造出 ~/.claude、~/.kiro 等目录。

脚本用 INSTALL_HOME 变量集中定位所有宿主根目录，默认 $HOME，可用 DBS_INSTALL_HOME 覆盖（便于测试与沙箱）

skills/dbs-install-skill/scripts/install-skill.sh

INSTALL_HOME="${DBS_INSTALL_HOME:-$HOME}"

共享入口 SHARED_TARGET_DIR="$INSTALL_HOME/.agents/skills"；专属入口为 6 个数组项，冗余清理目录为 24 个数组项。

实际落盘动作是符号链接（Unix）或目录 Junction（Windows），不复制源文件，因此源 Skill 更新后各宿主立即同步

skills/dbs-install-skill/SKILL.md

Unix-like 系统使用符号链接；Windows 的 Bash／MSYS 环境使用目录 Junction，避免 `ln -s` 在部分配置下生成实体目录副本。

脚本对应实现：create_managed_link 走 run_windows_junction 或 ln -s。

Grok 走「薄适配层」而非链接：脚本生成一个极小的 SKILL.md，frontmatter 带 user_invocable: true，正文只有指回真源的 Source of truth 行

skills/dbs-install-skill/scripts/install-skill.sh

- Source of truth: $src/SKILL.md

Grok 目录里不维护长逻辑（"Treat this file as a thin Grok bridge only"），真源改动单点生效。

Skill 名不取目录名，而取真源 SKILL.md frontmatter 的 name（脚本用 awk 只读 frontmatter 区），使源目录可以带分类前缀而各 Agent 触发名保持稳定

skills/dbs-install-skill/SKILL.md

入口名优先读取真源 `SKILL.md` frontmatter 中的 `name`；只有 `name` 缺失时才退回源目录名。这样源目录可以使用分类前缀，各 Agent 仍保持稳定的历史触发名。

awk 解析失败或 name 缺失时退回 basename；name 含 / 或为 . / .. 时直接 die，防路径逃逸。

每次 link 顺带做幂等清理：删除指向同一真源的冗余/历史别名/断裂链接，并保留真实目录与指向其他来源的链接（冲突则报告）

skills/dbs-install-skill/SKILL.md

删除公共入口兼容客户端专属目录中指向同一真源的冗余链接；

link_one 遇到已有真实目录/文件时打印 "✗ 是真实目录或文件，已保留" 并返回 2，绝不覆盖。

status 动作把「是否存在冗余入口」变成可判定的退出码语义：无冗余才输出 ✓，有冗余则报 ✗ 并失败

skills/dbs-install-skill/SKILL.md

状态正常时，脚本必须输出：

脚本末尾：仅当 action=status 且 failed=0 时打印 ✓ 未发现冗余入口，并以 failed 作为进程退出码。

2核心能力

01跨宿主安装：单 Skill 或整个 Skill 集合一次 link 到所有已装宿主

02集合目录安装：一级子目录里每个含 SKILL.md 的目录都会被逐一套用同一套路由

03安装状态体检与冗余判定（status 子命令）

04卸载只删派生产物，源 Skill 与用户真实目录绝不删除

05Windows 支持：用 PowerShell 助手管理 Junction 的 create/target/remove/test/list/same/under

06不覆盖真实目录／真实文件／他源链接，冲突时保留并报告

07源目录解析优先级：绝对路径 → 当前工作目录 → 仓库根 → 仓库 skills/<name>，找不到即报错而非猜

08入口稳定名：以真源 frontmatter name 为链接名，而非目录名

4管控建议与判定依据

建议配套管控措施

面向 Agent

分级或逐次授权，建议在沙箱运行

面向管理者

审批流程、可回滚、全程审计

判定依据（文件路径与关键语句摘要）

scripts/: 执行本地脚本或命令: skills/dbs-install-skill/scripts/install-skill.sh（bash，由模型按 SKILL.md 指示直接执行
环境变量 / API Key: 读取厂商服务密钥: 读取 $HOME 与 $DBS_INSTALL_HOME 以定位各 Agent 根目录（INSTALL_HOME="${DBS_INSTALL_HOM
本地工作目录: 文件读写与工件输出: ~/.agents/skills/<name> 及 6 个专属宿主目录下的符号链接/Junction（mkdir -p 目标目录）

审计说明： 。判级对象是本 skill 自身目录：它自带可执行脚本（809 行 bash + 157 行 PowerShell 助手），会以 bash/Windows PowerShell 实际操作用户主目录（建/删链接与 Junction、写一个 Grok 桥接 SKILL.md），属「仅本地脚本/CLI 与本地读写、无外发」档。无网络外发、无凭证读取、无包安装、无 eval；删除动作被严格限定为「指向当前指定真源的受管链接」与「本工具生成的 Grok 目录」，并对真实目录/真实文件/他源链接一律保留报告（退出码 2）。使用前应知道它会改动的路径范围在 $HOME 下、且默认不复制源文件。

5第二遍独立确认

[ok] 外部资源/工具：是否存在未披露的网络或第三方依赖 — skills/dbs-install-skill 整目录（SKILL.md + install-skill.sh + windows-junction.ps1 + agents/openai.yaml）token 扫描 curl/wget/https?:///api_key/token/secret/fetch 全部零命中；脚本只调用 ln/mkdir/rm/find/awk/sed/uname/dirname/basename 与（Windows 时）pwsh/powershell，均为本机命令。external_deps 记为空数组成立。
[ok] 安全结论：删除动作是否会危及用户既有文件 — unlink 路径只走 unlink_if_points_to（先比对链接目标是否等于本次真源）与 unlink_grok_one；Grok 分支的 rm -rf 前面有两道门：is_managed_link、或以 grep -q '^## Grok Bridge$' 判定为本工具生成的桥接文件，否则打印「✗ 是真实目录或文件，已保留」并 return 2。link 路径同理（link_one 遇 -e "$link" 即保留）。未发现无条件 rm -rf。
[discrepancy] SKILL.md 自检项「private/ 与 .private/ 没有被读取、复制、暂存或安装」是否由脚本兑现 — 该句仅出现在 skills/dbs-install-skill/SKILL.md:203；对整个 skill 目录 grep -rni private 只此一处，install-skill.sh 与 windows-junction.ps1 中均无任何 private/.private 过滤或跳过逻辑，仓库工具层 tools/test-dbs-install-skill*.sh 也无相关用例。真实行为是：脚本对源目录建链接/桥接，既不复制也不过滤子目录，因此源 Skill 目录内若存在 private/，它会随源目录一起被 Agent 目录侧访问到（不会产生副本）。该项属文档声明超前于实现，不构成凭空夸大宣传，但「没有被读取/安装」这一表述在脚本层面无证据。
[ok] 功能声明 vs 实际代码能力：SKILL.md 描述的宿主清单与脚本数组是否一致 — SKILL.md 专属入口列 6 家（Claude Code/WorkBuddy/Hermes Agent/Kiro/Qwen Code/Cline），对应 NATIVE_TARGET_DIRS 恰好 6 项；公共兼容客户端列 8 家（Codex/GitHub Copilot/Gemini CLI/Cursor/Augment/Roo Code/OpenCode/OpenHands），对应 REDUNDANT_TARGET_DIRS 前 8 项注释「前 8 项已能读取 ~/.agents/skills」，数组实际长度 24（其余为旧版目录，仅用于清理）。一致。
[unlocatable] 证据定位：stars/last_push/license 是否能在 pin 源码内定位 — stars=10121、last_push=2026-09-07 取自站点池 data/pool.json 的机器采集字段（GitHub API），pin 工作副本为本地镜像，源码内无此数据，无法在用 read 可及的仓库文件内逐字命中；license 可在仓库根 LICENSE 逐字命中（CC BY-NC 4.0）。

6结论

把「多端安装」这件重复劳动固化成一条命令，且默认零参数：路由靠探测宿主主目录存在性决定，用户不需要理解各 Agent 的目录约定

链接而非复制，天然消除多端版本漂移；且每次执行顺带收敛历史冗余入口，长期使用不会退化成一堆互不同步的副本

破坏性操作有明确的边界与失败语义：真实目录、真实文件、他源链接一律保留并返回非零，用户能立刻看出「哪里没被自动处理」

文档披露层级诚实：显式列出「不创建不存在的 Agent 主目录」「不覆盖真实目录」「卸载只删派生产物」「源 Skill 不会被删除」等约束，与脚本实现可逐条对上（private/ 一项除外）

适合： 适合同时使用 2 个以上 Agent 宿主（Claude Code + Codex + Cursor/Grok/Qwen Code…）的 skill 作者与重度用户：一份真源、一处维护、全端可见；也适合 skill 集合（如整个 dbskill 的 32 个 skill）批量分发与周期性去重体检（status 子命令可作为 CI/自检钩子）。

不适合： 不适合把 skill 当受版本控制的副本分发给他人（本工具刻意用链接，不做拷贝/打包）；不适合 Windows 上无 PowerShell 的环境；不适合希望「装到任意自定义目录」的场景——宿主目录是硬编码数组，唯一可改的是 INSTALL_HOME 根（DBS_INSTALL_HOME）。

Install Agent-Ready

① Verified Mirror 2026-09-15

Option A · Direct DownloadDownload dbs-install-skill.tar.gz

sha256: d04f021c0c5317a1…

Option B · Copy Guide for Agent

install.json

agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。

② Upstream GitHub

GitHub Repo ↗

Pinned to commit 8b8e33f1ec.