team-skills

team-skills

概述

浏览团队 AI 指令中提供的技能，并将选定的技能安装到当前 Agent 的技能目录。使用 --all 可一次性安装所有 default 和 external 技能。技能以其原始名称（无前缀）安装，以便与清单保持同步。

适用场景

• 用户要求浏览、列出或安装团队技能时。
• 输入中指定了要安装的技能时。
• 需要通过团队共享技能扩展 Agent 的能力时。
• 初始配置完成后，team-setup 委派执行 /team-skills --all 时。

$ARGUMENTS

核心流程

设置

直接读取文件 .adlc/init-options.json。不要使用 glob、find 或任何文件搜索工具来定位该文件——搜索工具可能会静默跳过以点号开头的路径段。从当前工作目录下的确切相对路径 .adlc/init-options.json 读取文件。

如果读取失败（文件不存在），则逐级向上读取父目录中的文件：先读取 ../.adlc/init-options.json，再读取 ../../.adlc/init-options.json，依此类推，最多向上 4 级。遇到首次读取成功时停止。

从 JSON 中提取 team_ai_directives 字段：

{
  "team_ai_directives": "/path/to/team-ai-directives"
}

如果未设置 team_ai_directives，则停止：

Team AI directives not configured.
Run: /team-setup

辅助脚本（以 team-setup 中的版本为准，相对于技能目录引用）：

• $(dirname "$0")/../team-setup/scripts/bash/team-helpers.sh --json
• $(Split-Path $PSCommandPath -Parent)/../team-setup/scripts/powershell/team-helpers.ps1 -Json

步骤 1：读取技能清单

读取 {REPO_ROOT}/.skills.json（其中 {REPO_ROOT} 表示项目根目录，即 .adlc/ 所在目录）和 {TEAM_AI_DIRECTIVES}/.skills.json（团队指令清单）。合并两者，以项目根目录中的条目为准。解析清单中的各个部分（schema v2.0.0）：

部分	说明	是否由 --all 安装？
default	本地技能（位于 skills/{name}/），设置期间自动安装	是
external	通过 URL 获取的远程技能，按需安装	是
blocked	已拒绝——绝不能安装	从不

步骤 2：显示可用技能

按部分分组展示技能。每项技能显示：

• 名称（键，例如本地技能的 github-actions，或远程技能的 react-best-practices）
• 描述
• 是否已安装（检查 Agent 技能目录）

格式：

Team Skills from {TEAM_AI_DIRECTIVES}

Default (local, installed by --all):
  [installed] dbt-template - DBT project templates and best practices
  [available] github-actions - GitHub Actions CI/CD pipeline patterns
  [available] helm-charts - Helm chart patterns for Kubernetes
  [available] crossplane - Crossplane Composition and XRD patterns
  [available] external-secrets - External Secrets Operator patterns
  [available] gke-workload-identity - GKE Workload Identity patterns

External (remote, installed by --all):
  [available] react-best-practices - React performance optimization
  [available] web-design-guidelines - Web interface best practices

步骤 3：安装选定的技能

根据参数确定安装目标：

• --all：安装所有 default 技能和所有 external 技能，跳过 blocked 中列出的技能以及已安装的技能。
• 技能名称：直接安装该技能。
• 无输入：询问用户要安装哪些技能。

确定 Agent 的技能目录：

1. 读取 .adlc/integration.json 以获取当前 Agent
2. 使用 {agent_folder}/skills/ 作为目标目录

以原始名称（无前缀）安装，frontmatter 中的 name 保持不变：

对于本地技能（default 列表——名称对应 skills/{name}/）：

1. 定位 {TEAM_AI_DIRECTIVES}/skills/{name}/SKILL.md
2. 将 SKILL.md 复制到 {skills_dir}/{name}/SKILL.md

对于远程技能（external 映射——条目包含 url）：

1. 先检查名称是否列在 blocked 中——如果是，立即拒绝。
2. 验证条目的 url 是否以 https:// 开头——拒绝其他任何协议（http://、file://、裸路径），并说明原因。
3. 向用户显示 URL 和目标位置，并在下载前征求确认（先预览，不得静默获取网络内容）。
4. 从条目的 url 字段下载 SKILL.md。
5. 保存到 {skills_dir}/{name}/SKILL.md。
6. 绝不执行下载的内容——安装仅表示复制文件。

绝不安装 blocked 中列出的技能。跳过目标位置中已存在的技能（将其报告为 [installed]）。

步骤 4：确认

Installed: github-actions
Location: .opencode/skills/github-actions/SKILL.md
Source: default (local:./skills/github-actions)

备注

• 默认技能通过 --all 安装，通常在初始配置后由 team-setup 调用，也可以随时手动运行。
• 技能以原始名称安装，不带 team- 前缀，因此磁盘上的名称与清单键一致。
• blocked 列表中的技能绝不会安装。
• 外部技能通过 HTTPS 从清单中的 URL 获取。

常见的错误认知

错误认知	为什么不对	应改为
“我会给已安装的技能添加 team- 前缀”	磁盘上的名称会与清单键不一致，导致查找失败	使用原始名称安装；frontmatter 中的 name 保持不变
“搜索工具会找到 .adlc/init-options.json”	glob/find 会静默跳过以点开头的路径段	直接读取确切的相对路径
“被阻止的技能只是强烈建议不要安装”	blocked 表示明确禁止安装	绝不安装被阻止的技能
“默认技能已在别处自动安装”	只有 --all（通过 team-setup 或手动运行）才会安装这些技能	运行 /team-skills --all，安装默认技能集
“我会跳过合并项目根目录中的清单”	项目条目旨在覆盖团队默认值	合并两个清单；冲突时以项目根目录为准

危险信号

• 使用 glob、find 或 grep 查找 .adlc/init-options.json，而不是读取确切路径。
• 安装时重命名技能或添加 team- 前缀——应使用原始名称安装，使其与清单一致。
• 安装 blocked 部分中列出的技能。
• 将技能写入 Agent 配置的技能目录以外的任何目录。
• team_ai_directives 字段未设置时仍继续操作，而不是停止并显示配置消息。
• 通过非 HTTPS URL 获取外部技能。

验证

• 已直接读取 .adlc/init-options.json（未使用搜索工具），并将 team_ai_directives 解析为一个路径。
• 已合并 {REPO_ROOT}/.skills.json 和 {TEAM_AI_DIRECTIVES}/.skills.json；发生冲突时以项目根目录条目为准。
• 每项已安装技能都位于 {skills_dir}/{name}/SKILL.md，且 frontmatter 中的 name 为原始名称（无前缀）。
• 未安装 blocked 部分中的任何技能。
• --all 安装了所有 default 和 external 技能（跳过 blocked 和已安装的技能）。
• 已输出确认信息块，显示已安装技能的名称、磁盘位置和来源。

配置

• TEAM_AI_DIRECTIVES — 团队 AI 指令的路径（覆盖 .adlc/init-options.json）。
• .adlc/init-options.json — 包含 team_ai_directives 字段的项目级配置文件。
• 默认回退路径：相对于项目根目录的 team-ai-directives/。
• ../team-setup/scripts/bash/team-helpers.sh / ../team-setup/scripts/powershell/team-helpers.ps1 — 用于解析路径的共享脚本（以 team-setup 中的版本为准）。

12 因子对齐

因子 XII（团队能力）——管理团队技能目录和安装。