Skip to content

[Feature]: 增加通用 ~/.agents/skills 全局安装目录(需兼容性验证) #194

Description

@legeling

Feature Description

建议在 Skill 分发/安装目标中,增加一个独立的 “通用 Agent Skills 全局目录(实验性)” 选项,默认指向用户目录下的:

~/.agents/skills

Windows 对应:

%USERPROFILE%\.agents\skills

初步观察是,越来越多智能体或 AI 编程工具可能会默认扫描并加载该目录。如果验证属实,用户只需将 Skill 安装一份到这个共享目录,就可以被多个兼容智能体读取,不必分别复制到每个平台的专属目录。

该判断目前需要进一步验证,建议先作为实验性能力和兼容性调研项,不应直接宣称所有平台均支持。

Motivation

PromptHub 当前主要按具体平台分发 Skill。同一个 Skill 若要提供给多个智能体使用,可能会被重复复制或分别建立链接,带来以下问题:

  • 多份 Skill 内容容易产生版本不一致;
  • 安装、更新和卸载需要逐个平台执行;
  • 平台目标越来越多,配置复杂度随之增加;
  • 如果多个平台原生支持 ~/.agents/skills,重复分发没有必要。

提供共享的全局安装目标,可以把符合通用 Agent Skills 约定的 Skill 维护在单一位置。

Proposed Solution

  1. 在 Skill 的“安装到平台”列表中增加一个独立目标:
    • 名称示例:Agent Skills(通用全局目录)
    • 默认目录:~/.agents/skills
    • Windows:%USERPROFILE%\.agents\skills
    • 支持用户覆写路径。
  2. 首期标记为“实验性”,并提示只有确认支持该目录的智能体才能读取。
  3. 与现有平台目标一样支持:
    • Copy / Symlink;
    • 安装、更新、卸载;
    • 冲突检测和本地修改保护。
  4. 若同时选择通用目录和平台专属目录,应检测潜在的重复加载并给出提示。
  5. 在 UI 或文档中展示经过实际验证的兼容性矩阵。

Validation Required

合入前建议逐个平台实际验证,而不是只根据目录命名推断:

  • 是否默认扫描用户级 ~/.agents/skills
  • 是否还支持项目级 <project>/.agents/skills
  • 是否需要配置开关或特定版本;
  • Skill 的目录结构和 SKILL.md 格式要求;
  • 与平台专属目录同时存在时的优先级、去重和冲突行为;
  • Copy 与 Symlink 在 macOS、Windows、Linux 上能否正常加载;
  • 平台升级后该路径是否仍保持兼容。

建议至少验证 Codex、Claude Code、Cursor、Gemini CLI、Windsurf、Cline、OpenCode 等 PromptHub 已支持的主要平台,再决定是否默认展示或转为稳定功能。

Acceptance Criteria

  • 建立并记录主要平台的实测兼容性矩阵;
  • 仅将实测支持的平台标记为兼容;
  • 可以把 Skill 安装到用户级 .agents/skills
  • 支持更新和卸载,且不会删除非 PromptHub 管理的文件;
  • 同时安装到共享目录和平台专属目录时有重复/冲突提示;
  • macOS、Windows、Linux 的路径解析正确;
  • 文档明确说明该能力的实验性质和适用范围。

Alternatives Considered

  • 继续只支持各平台专属目录:兼容性明确,但会重复安装和维护。
  • 由用户手动新增一个自定义 Agent 目标:可以临时绕过,但无法表达“多个 Agent 共享目录”的语义,也缺少统一的兼容性提示和冲突检测。

Additional Context

PromptHub 仓库本身已经使用项目级 .agents/skills 目录,这可以作为测试样例之一;但项目级目录可用并不能证明用户级 ~/.agents/skills 会被所有智能体默认加载,因此仍需逐个平台验证。

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions