How to Make Your Antigravity Agent Skills Configurable (Without Forking Them)

如何在不 fork 的情况下让 Antigravity Agent Skills 可配置

2026 年 7 月 29 日

/

#AI

Obum

Antigravity Agent Skills 是一种教 AI 代理学习工作流程并复用到所有场景的绝佳方式。你只需编写一个简短的 SKILL.md 文件，将其放入文件夹中，代理就会在相关时自动加载。

但这些技能有一个隐藏的限制：它们是静态的。如果你下载了别人写的技能并希望它行为略有不同，就必须复制整个文件并手动编辑。你可能已经注意到，目前存在许多难以维护的“技能”fork版本。

在本教程中，我将展示我构建的一个小技巧，可以解决这个问题。它允许任何 Agent Skill 读取项目专属的配置文件，这样你就可以通过编辑几行 YAML 来采用任何技能并自定义其行为（而无需触碰技能本身）。

你将逐步构建它、进行测试，并了解如何分享它以便其他人可以使用。

目录

• 你将构建的内容

• 先决条件

• 什么是 Antigravity Agent Skills ?

• 为什么静态技能存在问题

• 可配置技能的解决方案

• 如何构建配置加载器

• 如何使技能可配置

• 如何添加项目覆盖

• 如何测试你的可配置技能

• 两个更多示例技能

• 如何与他人共享你的 Agent Skills

• 总结

你将构建的内容

你将构建一个名为 Configurable Agent Skills 的微型可复用层。它包含三个部分：

• 一个小型 Python 脚本 resolve_config.py，它将技能的默认设置与你的项目设置合并并输出结果。

• 一种约定：每个技能包含 2 个文件，一个包含其"控制旋钮"的 config.default.yaml 文件和一个 SKILL.md 文件。它们共同指导代理的行为。

• 一个项目专属文件 .agent/skills.config.yaml，任何使用你的技能的人都可以在这里设置自己的值。

最终，你将获得一个可用的 git-commit-formatter 技能，一个团队可以以 Conventional Commits 模式运行，另一个团队可以切换到 gitmoji 模式，所有团队都使用完全相同的技能文件而无需 fork。

先决条件

要跟随本教程，你需要：

• 安装 Google Antigravity（IDE、CLI 或 SDK 均可，因为技能只是文件）。

• 安装 Python 3 和 PyYAML。你可以通过 python -m pip install pyyaml 安装 PyYAML。

• 对终端和 YAML 有基本的熟悉度。你不需要是专家。

如果你从未编写过 Agent Skill，接下来的两个部分将帮助你快速入门。

什么是 Antigravity Agent Skills ?

Antigravity 中的 Skill 是一个包含 SKILL.md 文件的文件夹，可选地包含一些脚本、模板或示例。SKILL.md 文件顶部有一个简短的 YAML "frontmatter" 块（包含名称和描述），后面跟着用普通 Markdown 编写的指令集。

重要的是：技能是按需加载的。代理首先只会读取每个技能的简短描述。当你的请求匹配该描述时，代理会加载完整的指令并执行。这使代理的上下文保持小巧且专注。

一个强制使用 Conventional Commits 的最小技能如下所示：

---
name: git-commit-formatter
description: 使用 Conventional Commits 规范格式化 git 提交信息。当用户要求提交更改或编写提交信息时使用此技能。
---

# Git 提交格式化器

当编写提交信息时，请遵循 Conventional Commits 格式： type(scope): description

允许的类型：feat, fix, docs, style, refactor, perf, test, chore.

将技能放入你的技能文件夹，让代理执行 "commit these changes" 操作，它会自动生成格式正确的提交信息。是不是既简单又实用？

## 为什么静态技能存在问题

现在仔细看一下这个技能。允许的类型（feat、fix、docs 等）是直接硬编码在指令中的。

这在需求稍有变化时就会出现问题。也许你的团队还使用了 ci 类型。也许你更倾向于使用 gitmoji，让每个提交都以表情符号开头。也许你希望强制每个提交都包含作用域。

对于静态技能来说，要实现这些需求只能通过复制整个技能并修改 Markdown 文件。当团队成员都这么做时，每个人都会维护自己的私有分支。当原始作者发布改进时，所有分支都无法获得更新。技能逐渐从共享工具变成了每个人都要重写的私有内容。

核心问题在于技能逻辑（应该共享的部分）和设置参数（每个项目需要自定义的部分）之间缺乏清晰的界限。我们该如何解决这个问题？

## 可配置技能方案

思路很简单。不要将设置参数硬编码在指令中，而是让技能：

- 将配置参数及其默认值存储在单独的 config.default.yaml 文件中。

- 在执行操作前，读取合并后的配置（默认值加上任何项目级覆盖设置）。

项目级覆盖设置存储在名为 .agent/skills.config.yaml 的文件中，该文件位于用户项目的根目录：

.agent/skills.config.yaml

#（请在项目中编辑此文件，而不是全局修改技能） git-commit-formatter: style: gitmoji extra_types: [ci, build] scope_required: true

这就是简单的使用流程。将技能放入后设置几个关键参数即可完成。技能本身的文件永远不会被修改。

要实现这个方案，你需要一个脚本，它需要读取两个文件，合并它们并将结果传递给代理。让我们来构建这个脚本。

## 如何构建配置加载器

创建一个名为 resolve_config.py 的文件。它的任务是接收技能名称，加载该技能的 config.default.yaml 文件，找到用户的 .agent/skills.config.yaml 文件，并将两者合并，使用户设置具有优先权。

首先从深度合并辅助函数开始。这是加载器的核心：

def deep_merge(base, override): """递归地将 override 合并到 base 中。

字典按键合并。其他类型（标量、列表）则直接由 override 值替换。 """ if isinstance(base, dict) and isinstance(override, dict): merged = dict(base) for key, value in override.items(): merged[key] = deep_merge(merged[key], value) if key in merged else value return merged return override

注意这里的设计选择：字典按键合并，但列表会被整体替换而不是追加。这能保持行为的可预测性。如果需要处理"默认值+额外项"的情况，可以像下面示例中那样，在技能中使用显式的 extra_types 键。

接下来你需要找到"项目级"配置。加载器会从当前目录向上遍历，寻找 .agent/skills.config.yaml 文件：

from pathlib import Path

def find_project_config(start: Path): """从 start 向上遍历查找 .agent/skills.config.yaml 文件.""" start = start.resolve() for folder in [start, *start.parents]: candidate = folder / ".agent" / "skills.config.yaml" if candidate.is_file(): return candidate return None

现在将它们组合起来。加载器会定位技能的默认配置（位于脚本旁边），加载该技能名称的覆盖设置，合并后输出结果：

import sys, yaml from pathlib import Path

def resolve(skill_name, skill_dir, project_root): defaults = yaml.safe_load((Path(skill_dir) / "config.default.yaml").read_text()) or {}

user_path = find_project_config(Path(project_root)) user_all = yaml.safe_load(user_path.read_text()) if user_path else {} user_cfg = (user_all or {}).get(skill_name, {}) or {}

return deep_merge(defaults, user_cfg)

这完成了整个思路。示例仓库中的完整版本增加了命令行界面、JSON 输出和清晰的错误提示，但上述逻辑已经是你真正需要的核心部分。

## 如何使技能可配置

现在你将把静态的提交技能转换为可配置的版本。这需要两个文件。

首先，在技能旁边创建 config.default.yaml 文件。它列出了每个设置及其安全默认值，即使用户没有任何配置，技能也能正常工作：

git-commit-formatter 技能的默认配置。

style: conventional # conventional | gitmoji types: # 允许的提交类型基础集合

• feat
• fix
• docs
• style
• refactor
• perf
• test
• chore

extra_types: [] # 额外类型，叠加在 types 之上 scope_required: false # 如果为 true，必须指定作用域：type(scope): ... max_subject_length: 72 # 主题行的硬性长度限制

其次，更新 SKILL.md，使其第一条指令就是解析配置并应用。这是关键步骤：你告诉代理在执行任何其他操作之前先读取设置：

name: git-commit-formatter description: 格式化 git 提交信息为团队选择的规范（Conventional Commits 或 gitmoji）。当用户要求提交更改或撰写提交信息时使用此技能。读取项目特定的设置，使团队无需修改此技能即可自定义提交样式。

Git 提交格式化器（可配置）

步骤 1 - 解析配置（始终首先执行）

运行加载器并读取输出：

python scripts/resolve_config.py git-commit-formatter --project-root .

应用这些设置：

• style: conventional 或 gitmoji。
• types + extra_types: 允许的完整提交类型集合。
• scope_required: 如果为 true，必须指定作用域。
• max_subject_length: 主题行的硬性长度限制。

步骤 2 - 构建信息

从 types + extra_types 中选择主类型，按选定的 style 构建主题，并强制执行 scope_required 和 max_subject_length。

这种模式（“让代理运行脚本并遵循其输出”）是 Antigravity 自己的验证技能所使用的。它通过让行为保持确定性，而不是依赖模型的记忆，从而保持一致性。

注意 extra_types 如何解决增加列表项的问题。默认列表保持不变，用户的额外项只需由技能简单叠加即可。无需分叉即可添加 ci 类型。

## 如何添加项目覆盖

假设你希望使用带有两种额外类型的 gitmoji 提交。在项目中创建一个单独的文件：

.agent/skills.config.yaml

git-commit-formatter: style: gitmoji extra_types: [ci, build] scope_required: true

你只需修改了三行配置，而无需打开技能或 fork 任何代码。下一次代理提交时，它将使用这个项目的设置。

而另一个没有任何配置文件的项目，仍然会使用合理的 Conventional Commits 默认值。你拥有一个技能，但可以实现多种行为。

## 如何测试你的可配置技能

你不需要让代理验证合并是否有效。直接运行加载器并查看输出结果即可。

在没有覆盖设置时，你会得到默认值：

$ python scripts/resolve_config.py git-commit-formatter --project-root . style: conventional scope_required: false ...

现在添加上一节中的 `.agent/skills.config.yaml` 覆盖配置并再次运行：

$ python scripts/resolve_config.py git-commit-formatter --project-root . --print-sources style: gitmoji scope_required: true extra_types:

• ci
• build

types:

• feat
• fix
• docs

...

样式已切换为 gitmoji，scope_required 变为 true，你的额外类型也出现了（而基础类型列表保持完整）。这验证了合并确实实现了你想要的效果。

编写一个小型自动化测试也很有价值，这样加载器的未来更改就不会悄无声息地破坏合并。测试可以创建一个假技能和一个假项目配置到临时文件夹中，运行加载器，并断言用户值覆盖默认值，而未修改的默认值仍然保留。

## 两个更多示例技能

同样的模式适用于任何技能。这里再举两个例子说明其适用范围。

### 一个变更日志生成器

其 config.default.yaml 暴露了输出格式（如 Keep a Changelog），要包含的提交类型，以及是否将提交哈希链接到仓库 URL。一个项目可以生成按类型分组的正式变更日志，而另一个项目可以生成简单的项目符号列表。这是同一个技能，但配置不同。

changelog-generator config.default.yaml（节选）

format: keepachangelog # keepachangelog | conventional | simple include_types: [feat, fix, perf] include_authors: false repo_url: "" # 如果设置，哈希将链接到提交

### 一个许可证头添加器

其配置暴露了许可证（Apache-2.0、MIT 或自定义）、持有者，以及文件扩展名到注释风格的映射。公司只需在项目配置中设置一次持有者，每个新文件都会自动获得正确格式的许可证头，无需修改技能。

license-header-adder config.default.yaml（节选）

license: apache-2-0 # apache-2-0 | mit | custom holder: "Your Name or Org" year: auto # auto = 当前年份

关键在于几乎所有技能都内置了一些决策。当你将这些决策提取到 config.default.yaml 中时，你就能将一次性技能转化为任何人都可以复用和调整的工具。

- 发布一个小型索引：一个简单的 index.json 文件，列出每个技能的名称、路径和配置键，使其他人能够轻松发现你所构建的内容，并贡献他们自己的技能。

由于惯例只是“先读取配置文件”，任何人都可以发布一个兼容的技能。每个新的可配置技能都会使整个生态系统更加实用。除了发布技能本身，你还在发布一个其他人可以构建的微小标准。

## 总结

你从一个静态技能开始，其行为被固定在 Markdown 中，然后你将其转换为一个任何人都可以通过单个项目文件进行调整的可配置技能。

整个设置相对较小。它包含一个合并函数、一个惯例，以及每个技能的 config.default.yaml 文件。

它还改变了技能共享的方式。你不再需要通过复制技能来更改一个设置，而是可以保留共享的逻辑并调整自己的配置。技能的改进将传递给每个人，每个人仍然可以得到他们想要的行为。

如果你想尝试，按照本教程构建 git-commit-formatter 技能，将其放入你的 Antigravity 技能文件夹中，并在项目中添加一个 .agent/skills.config.yaml 文件。然后将 style 从 conventional 改为 gitmoji，观察同一个技能表现出不同的行为。

从那里开始，让你自己的技能变得可配置。找到你嵌入到说明中的设置，将它们移动到 config.default.yaml 中，然后让你的用户从那里继续。

完整的示例代码（加载器、其测试以及三个示例技能）可以在 GitHub 上找到：github.com/keepdeploying/configurable-agent-skills 。

感谢阅读。如果你构建了自己的可配置技能，请分享出来。让我们继续推动生态系统的增长。

(Obumuneme Nwabude) || 全栈区块链、移动和网页开发人员 || Google 开发者专家（GDE）Dart & Flutter。

如果你读到这里，请向作者表示感谢，以表明你对他们的关心。说声谢谢

免费学习编程。freeCodeCamp 的开源课程已帮助超过 40,000 人成为开发人员。立即开始

ADVERTISEMENT