organise-agent-skills

整理 Agent 技能

重要

强制用户确认防护措施：未经用户明确确认，不得删除任何技能目录、在配置文件（skills.json）中停用/启用技能，或修改配置/规则文档（GEMINI.md、AGENTS.md、README.md）。必须先向用户展示审计结果、拟议操作和令牌指标，并获得用户明确确认后方可继续。

此技能提供了一套可重复、结构化的工作流，用于在 Antigravity 和 Gemini 环境中审计、精简和整理 Agent 技能。它确保提示词上下文窗口保持精简（每轮交互约 30–50 个活跃技能 / 约 3,000 个令牌的开销），同时仍可完整使用所有已安装的技能。

目录

• 概览与令牌预算
• 技能生命周期与状态
• 工作流阶段 1：审计与发现
• 工作流阶段 2：元技能委派
• 工作流阶段 3：按需规则（GEMINI.md / AGENTS.md）
• 工作流阶段 4：可移植性与 skills.json 排除项
• 工作流阶段 5：更新文档

---

概览与令牌预算

每当 Agent 开始一轮交互时，所有**已安装且未激活（可发现）**技能的 name 和 description 都会注入系统提示词上下文。

• 问题：技能过度累积（100 个以上可发现技能）会导致每轮交互都注入 6,000–10,000 多个令牌，浪费上下文预算，并使大模型在决策时感到疲劳（由于描述重叠而产生幻觉或选择错误的技能）。
• 目标状态：保持一个精简的核心技能集，包含约 30 到 50 个可发现技能（提示词开销约 3,000 个令牌），将专业技能或子技能设为已安装且已排除，并使用元技能路由和 GEMINI.md 激活规则处理其他所有技能。

---

技能生命周期与状态

在 Agent 开发环境（如 Antigravity）中，技能具有三种明确的状态：

1. 已安装且未激活（可发现）：这些技能存在于磁盘上，并可供我们的 Agent 发现。Agent（例如 Antigravity）启动时，会自动将其前置元数据（第 1 层）读入上下文。在 skills.json 中，这些条目以 // 为前缀，或未被排除。
2. 已安装且已排除：这些技能保存在磁盘库中，但已从自动加载第 1 层内容中_排除_。对于这些技能，Agent 不会自动读取其前置元数据，因此在你与它对话时不会直接了解这些技能。不过，由于这些技能存在于磁盘上且可供 Agent 使用，因此仍可显式激活。在 skills.json 中，这些条目以普通字符串列出，不带 //。
3. 已激活：这是运行时状态，表示某个技能的完整 SKILL.md 正文已加载到当前轮次的上下文中。也就是说，加载了第 2 层；如果存在适用的支持文件，则还会加载第 3 层。

---

工作流阶段 1：审计与发现

1. 文件系统自动发现与完整清单审计：

   • 独立技能：列出磁盘上 ~/.gemini/config/skills/（以及工作区中的 .agents/skills/）下的所有技能目录。
   • 打包插件技能：检查 ~/.gemini/config/plugins/*/skills/ 中所有捆绑的技能。（对于 Antigravity，未列入 skills.json 的打包插件技能默认也会被发现，并会在不显眼的情况下增加提示词开销。）
   • 读取 skills.json（~/.gemini/config/skills.json），并将磁盘上的所有目录与 exclude 数组中的条目进行比对。
   • 识别差异：
     • 新发现的技能：磁盘上存在、但 skills.json 中缺失的独立技能文件夹。
     • 未列出的插件技能：磁盘上存在、但 skills.json 中没有的插件技能。
     • 孤立条目：skills.json 中存在（带有或不带有 //）但磁盘上已无对应目录的条目。
     • 已安装且已排除的技能：skills.json 中列出的技能，且字符串前缀不含 //。
     • 已安装且未激活（可发现）的技能：skills.json 中列出的技能，且字符串前缀含有 //。

2. 测量提示词占用：

   • 汇总所有当前可发现技能（包括未列出的插件技能）的描述词数／令牌数。
   • 检查可发现技能总数是否超过 30–50 个技能的理想范围（约 3,000–3,500 个令牌）；超过后会触发 Antigravity 的上下文预算管理器自动丢弃技能。

3. 强制语义与功能重叠审计： Agent 必须系统地检查技能清单，找出重复、过时或冗余的技能。不要仅依赖字面的文件夹名称或字符串距离匹配。

   • 语义与方法分析： 解析每项技能的 YAML frontmatter（description）、主要标题和操作指令。查找因文件夹名称不同而隐藏的共同软件工程方法或重叠工具。 示例：名为 conductor 的扩展插件与名为 spec-driven-development 的独立技能重复，因为两者都实现了规范驱动开发（SDD）工作流。

   • 功能领域聚类： 按语义领域对技能进行分组，并标记存在多个当前激活技能相互竞争或造成路由冲突的聚类：

     • Gemini API 与 SDK：例如 gemini-api 与 gemini-api-dev／gemini-interactions-api。
     • 规范驱动开发与规划：例如 spec-driven-development 与 conductor／planning-and-task-breakdown。
     • 浏览器 DevTools 与自动化：例如 chrome-devtools 与 browser-testing-with-devtools／playwright-cli。
     • 云身份验证：例如 gcloud-auth-verification 与 google-cloud-auth-verification。
     • 工作流编排：例如 gcp-composer-troubleshooting 与 managed-airflow-dag-troubleshooting。
     • 数据平台与存储：例如 BigQuery、Spark、Dataproc、GCS。

   • 打包插件替代情况： 将独立技能与官方打包扩展插件（config/plugins/）交叉比对。当上游插件已捆绑涵盖某个领域的技能时，独立副本即已过时：

     • 标记应从磁盘删除的过时独立技能。
     • 确保从 ~/.agents/.skill-lock.json 中清理已删除的技能，避免 npx skills update -g -y 重新下载它们。
     • 确保 .gitignore 中包含正则表达式模式（[-_]），以忽略插件技能的独立版本。

   • 行动：在执行前提案中明确建议删除冗余技能目录，并停用重叠版本。

工作流阶段 2：元技能委派

识别用于编排子技能的主元技能：

1. 主路由器：

   • 例如，技能 using-agent-skills 可编排 23 个资深工程 SDLC 子技能。
   • 例如，技能 google-agents-cli-workflow 可编排 ADK Agent 开发子技能（scaffold、code、deploy、eval、observability）。
   • 例如，技能 gcp-data-pipelines 可编排 Dataflow、Dataform、dbt、Dataproc 和 BigQuery 数据管道工具。

2. 操作：

   • 在 skills.json 中保持主元技能启用（例如 "//using-agent-skills"）。
   • 在 skills.json 中禁用子技能（不带 // 的普通字符串）。
   • 主元技能会指示 Agent 按需检查并读取磁盘上的子技能文件。

---

工作流阶段 3：按需规则（GEMINI.md / AGENTS.md）

每当在 skills.json 中禁用某个专用或小众领域技能（非主元技能的子技能）时，必须确保 GEMINI.md 或 AGENTS.md 中存在激活规则，让 Agent 知道何时按需启用或检查该技能。

1. 在 skills.json 中禁用：

   • 默认将领域技能排除在自动提示词注入之外（例如，在 exclude 中使用普通字符串）。

2. 必须在 GEMINI.md 或 AGENTS.md 中生成规则：

   • 在 ## Knowledge Rules 下检查 GEMINI.md（工作区技能则检查 AGENTS.md）。
   • 如果尚无针对已禁用领域技能的激活规则，必须使用以下模板起草并追加一条激活规则：

   ### <Domain / Skill Name> Activation Rule
   
   The `<skill-name>` skill is disabled by default in `skills.json` to keep context window overhead lean.
   
   **Activation Rule**: Activate or inspect `<skill-name>` (by adding `//` in `skills.json` or reading on demand) whenever <specific scenario, task type, or trigger conditions>.
   

   示例：

   • GCS Security Assessment（gcs-security-assessment）：每当审计存储桶访问控制、存储安全态势或 SAIF 合规性时启用。
   • NotebookLM Auth（notebooklm-auth）：每当诊断或解决 NotebookLM MCP Cookie 或身份验证错误时启用。

---

工作流阶段 4：可移植性与 skills.json 全量清单管理

为确保最高可见性并便于切换，skills.json 被视为所有已安装技能的显式全量清单控制面板，而非仅列出排除项的部分清单。

Antigravity skills.json 机制

• 位置：~/.gemini/config/skills.json（或工作区 .agents/skills.json）。
• 已安装且已排除：在 exclude 数组中使用普通字符串（例如 "alloydb-basics"）。完全匹配的结果为 true，因此会将该技能排除在 Level 1 提示词加载之外。
• 已安装且未激活（可发现）：在 exclude 数组中使用 // 前缀（例如 "//bigquery-sql"）。// 前缀会破坏精确字符串匹配（exclude.includes("bigquery-sql") 的结果为 false），使加载器将该技能视为可发现（其 frontmatter 会自动读取到 Level 1 提示词上下文中）。

对账与自动同步流程

执行 organise-agent-skills 时：

1. 自动注册缺失技能：将在磁盘上找到、但 skills.json 中不存在的所有技能文件夹添加进去。根据用户偏好或 Token 预算策略，将新注册的技能默认设为可发现（"//skill-name"）或排除（"skill-name"）。
2. 清理孤立条目：从 skills.json 中移除对应磁盘目录已不存在的条目。
3. 按字母顺序排序：保持 exclude 数组按字母顺序排列，使扫描和差异比较保持整洁、可预测。

skills.json 示例：

{
  "exclude": [
    "accidental-data-loss-prevention", // INSTALLED AND EXCLUDED (no // prefix)
    "//agent-aware-cli",               // INSTALLED AND INACTIVE / DISCOVERABLE (// prefix workaround)
    "//using-agent-skills",            // INSTALLED AND INACTIVE / DISCOVERABLE (Master Meta-Skill)
    "spec-driven-development"          // INSTALLED AND EXCLUDED (Sub-skill activated on-demand)
  ]
}

可移植性说明

• skills.json 是 Antigravity 环境的原生排除机制。
• 对于其他 Agent 框架（例如 Claude Code、Cursor、Windsurf），技能排除通过工作区 .agents/ 边界或工具配置文件管理。通过元技能禁用技能并按需读取文件的方式，仍可在所有大模型 Agent 之间 100% 移植。

---

工作流阶段 5：用户响应与文档更新

1. 执行前提案： 向用户展示审计结果、冗余技能明细和拟议操作，并附上汇总提案表：

   指标	基线（未优化）	拟议方案（已优化）	差值
   已安装的技能目录	N	M	-X
   已安装且可发现的技能	N	M	-X
   已安装且已排除的技能	N	M	+X
   提示词 Token 开销	~A tokens	~B tokens	-C tokens

   在进行任何文件删除或配置更改之前，先征求用户的明确确认。

2. 执行后汇总表： 获得批准并完成执行后，提供最终指标表，列出精确差值，并清晰说明所做的更改：

   • 已安装且可发现的技能：其 frontmatter 已预加载到第 1 级提示词上下文中的技能。
   • 已安装且已排除的子技能：由父级元技能按需读取并激活的技能。
   • 已安装且已排除的按需技能：通过 GEMINI.md / AGENTS.md 规则激活的技能。
   • 已安装且已排除的领域技能：在明确激活之前保持排除状态的细分／专业技能。
   • 已删除／停用的技能：从磁盘中移除的过时或重复技能。

3. 文档更新： 始终更新项目 README.md，记录当前启用的技能配置和元技能层级。