技能可以让你教会AI代理一个工作流，然后重复使用。但技能是静态的，导致它们难以定制、更新和复用。在这里，@obumnwabude 展示了如何让 Antigravity 技能变得可配置，而不是分叉原始技能。https://freecodecamp.org/news/make-your-antigravity-agent-skills-configurable-without-forking-them/…

如何让你的 Antigravity 代理技能变得可配置（无需分叉它们）

来源：https://www.freecodecamp.org/news/make-your-antigravity-agent-skills-configurable-without-forking-them/ 如何让你的 Antigravity 代理技能变得可配置（无需分叉它们）Antigravity 代理技能是一种绝佳方式，可以让你一次性教会AI代理一个工作流，并在任何地方重复使用。你只需编写一个简短的SKILL.md文件，将其放入文件夹，当代理认为相关时便会使用它。

但这些技能有一个隐藏的限制：它们是静态的。如果你下载了别人编写的技能并希望其行为稍有不同，你必须复制整个文件并手动编辑。正如你可能最近注意到的，有许多“技能”分叉在流传，维护起来非常困难。

在本教程中，我将向你展示我构建的一个小约定，它能解决这个问题。它让任何代理技能都能读取每个项目的配置文件，这样你就可以采纳任何技能，并通过编辑几行 YAML（从不触碰技能本身）来自定义其行为。

你将一步一步构建它，进行测试，并了解如何分享它，以便其他人可以接入。

目录

• 你将构建什么 (https://www.freecodecamp.org/news/make-your-antigravity-agent-skills-configurable-without-forking-them/#heading-what-you-will-build)
• 前提条件 (https://www.freecodecamp.org/news/make-your-antigravity-agent-skills-configurable-without-forking-them/#heading-prerequisites)
• 什么是 Antigravity 代理技能 (https://www.freecodecamp.org/news/make-your-antigravity-agent-skills-configurable-without-forking-them/#heading-what-are-antigravity-agent-skills)?
• 为什么静态技能是个问题 (https://www.freecodecamp.org/news/make-your-antigravity-agent-skills-configurable-without-forking-them/#heading-why-static-skills-are-a-problem)
• 可配置技能解决方案 (https://www.freecodecamp.org/news/make-your-antigravity-agent-skills-configurable-without-forking-them/#heading-the-configurable-skills-solution)
• 如何构建配置加载器 (https://www.freecodecamp.org/news/make-your-antigravity-agent-skills-configurable-without-forking-them/#heading-how-to-build-the-config-loader)
• 如何让技能可配置 (https://www.freecodecamp.org/news/make-your-antigravity-agent-skills-configurable-without-forking-them/#heading-how-to-make-a-skill-configurable)
• 如何添加项目覆盖 (https://www.freecodecamp.org/news/make-your-antigravity-agent-skills-configurable-without-forking-them/#heading-how-to-add-project-overrides)
• 如何测试你的可配置技能 (https://www.freecodecamp.org/news/make-your-antigravity-agent-skills-configurable-without-forking-them/#heading-how-to-test-your-configurable-skill)
• 另外两个示例技能 (https://www.freecodecamp.org/news/make-your-antigravity-agent-skills-configurable-without-forking-them/#heading-two-more-example-skills)
• 如何与他人分享你的代理技能 (https://www.freecodecamp.org/news/make-your-antigravity-agent-skills-configurable-without-forking-them/#heading-how-to-share-your-agent-skills-with-others)
• 总结 (https://www.freecodecamp.org/news/make-your-antigravity-agent-skills-configurable-without-forking-them/#heading-wrapping-up)

你将构建什么

你将构建一个微小、可复用的层，称为可配置代理技能。它包含三个部分：

1. 一个小的 Python 脚本 resolve_config.py，它合并技能的默认设置和你项目的设置，并输出结果。
2. 一个约定：每个技能附带两个文件：一个 config.default.yaml 文件，包含其“旋钮”；一个 SKILL.md 文件。它们共同指导代理的行为。
3. 一个项目级文件 .agent/skills.config.yaml，任何使用你的技能的人都可以在其中设置自己的值。

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

前提条件

要跟随学习，你需要：

• 安装 Google Antigravity（IDE、CLI 或 SDK 均可，因为技能只是文件）。
• 安装 Python 3 和 PyYAML。你可以通过 python -m pip install pyyaml 安装 PyYAML。
• 基本熟悉终端和 YAML。你不需要成为其中任何一个的专家。

如果你从未写过代理技能，接下来的两个部分会让你快速了解。

Antigravity 中的技能是一个包含 SKILL.md 文件（可选地包含一些脚本、模板或示例）的文件夹。SKILL.md 文件顶部有一个简短的 YAML “frontmatter” 块（包含 name 和 description），后面跟着用纯 Markdown 编写的一组指令。

这里有一个重要的部分：技能是按需加载的。代理最初只读取每个技能的简短 description。当你的请求与该描述匹配时，代理会拉入完整指令并遵循它们。这使代理的上下文保持小巧且集中。

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

``

name: git-commit-formatter description: Formats git commit messages using the Conventional Commits specification. Use this when the user asks to commit changes or write a commit message.

Git Commit Formatter

When writing a commit message, follow the Conventional Commits format: type(scope): description

Allowed types: feat, fix, docs, style, refactor, perf, test, chore. ``

将其放入你的技能文件夹，让代理“提交这些更改”，它将编写一个格式正确的消息。简单且有用，对吧？

为什么静态技能是个问题

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

这没问题，直到有人想要稍微不同的东西。也许你的团队也使用 ci 类型。也许你更喜欢 gitmoji，其中每个提交都以表情符号开头。也许你希望在每个提交上强制要求一个范围（scope）。

对于静态技能，只有一种方法可以实现这些：复制整个技能并编辑 Markdown。当你在团队中这样做时，每个人最终都有自己的私有分叉。当原始作者发布改进时，没有分叉会得到它。技能不再是你分享的东西，而是每个人重写的东西。

核心问题在于，技能的逻辑（每个人都应分享）和它的设置（每个项目都想控制）之间没有清晰的界限。我们如何解决这个问题？

可配置技能解决方案

想法很简单。技能不会在指令中硬编码设置，而是：

1. 在单独的 config.default.yaml 文件中存放其设置和默认值。
2. 在行动之前读取合并后的配置（默认值加上任何项目级覆盖）。

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

``

.agent/skills.config.yaml

(edit this file in your project instead of the skill globally)

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): “”“Recursively merge override onto base.

Dicts merge key by key. Anything else (scalars, lists) is replaced
wholesale by the override value.
"""
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): “”“Walk upward from start looking for .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 输出和清晰的错误消息，但上述逻辑就是你真正需要的。

终端输出显示了 git-commit-formatter 技能的已解析配置。## 如何让技能可配置

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

首先，在技能旁边创建 config.default.yaml。它列出每个设置和一个安全默认值，以便即使用户没有任何配置，技能也能工作：

``

Default configuration for the git-commit-formatter skill.

style: conventional # conventional | gitmoji types: # base set of allowed commit types

• feat
• fix
• docs
• style
• refactor
• perf
• test
• chore extra_types: [] # additional types, merged on top of types scope_required: false # if true, require a scope: type(scope): … max_subject_length: 72 # hard cap on the subject line ``

其次，更新 SKILL.md，使其第一个指令就是解析配置并应用它。这是关键动作：你告诉代理在它做任何其他事情之前读取设置：

``

name: git-commit-formatter description: Formats git commit messages to a team’s chosen convention (Conventional Commits or gitmoji). Use this when the user asks to commit changes or write a commit message. Reads per-project settings so teams customize commit style without editing this skill.

Git Commit Formatter (Configurable)

Step 1 - Resolve configuration (always do this first)

Run the loader and read its output:

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

Apply exactly those settings:

• style: conventional or gitmoji.
• types + extra_types: the full set of allowed commit types.
• scope_required: if true, a scope is mandatory.
• max_subject_length: hard cap on the subject line.

Step 2 - Compose the message

Pick the primary type from types + extra_types, build the subject in the chosen style, and enforce scope_required and max_subject_length. ``

这种模式（“让代理运行脚本并服从其输出”）与 Antigravity 自己的验证技能使用的模式相同。它使行为具有确定性，而不是留给模型的记忆。

注意 extra_types 如何解决加法列表问题。默认列表保持不变，用户额外的类型由技能简单地添加到上面。添加 ci 类型无需分叉。

如何添加项目覆盖

假设你想要带有两个额外类型的 gitmoji 提交。在你的项目中创建一个文件：

``

.agent/skills.config.yaml

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

你刚刚更改了三行配置，没有打开技能或分叉任何代码。下次代理提交时，它将使用这个项目设置。

而另一个没有配置文件的项目，则继续使用合理的 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 … ``

style 变为 gitmoji，scope_required 变为 true，你的额外类型出现了（而基础 types 列表保持不变）。这确认了合并完全按照你的期望工作。

编写一个小型自动化测试也值得，这样未来对加载器的更改不会悄无声息地破坏合并。测试可以在临时文件夹中创建一个假技能和一个假项目配置，运行加载器，并断言用户值覆盖了默认值，而未触及的默认值保持不变。

另外两个示例技能

同样的模式适用于任何技能。这里还有两个示例来展示其范围。

变更日志生成器

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

``

changelog-generator config.default.yaml (excerpt)

format: keepachangelog # keepachangelog | conventional | simple include_types: [feat, fix, perf] include_authors: false repo_url: “” # if set, hashes link to commits ``

许可证标头添加器

它的配置暴露了 license（Apache-2.0、MIT 或自定义）、holder 以及文件扩展名到注释样式的映射。公司在其项目配置中设置一次 holder，每个新文件都会获得正确的标头，使用正确的注释样式，无需编辑技能。

``

license-header-adder config.default.yaml (excerpt)

license: apache-2.0 # apache-2.0 | mit | custom holder: “Your Name or Org” year: auto # auto = current year ``

教训是，几乎任何技能都有一些内置的决策。当你将这些决策提取到 config.default.yaml 中时，你就把一个一次性的技能变成了一个任何人都可以复用和调整的工具。

如何与他人分享你的代理技能

一旦你的代理技能遵循这个约定，它们就可以组合成更大的东西。为了让你的代理技能易于他人采纳，你需要：

• **保持每个技能自包含：**在每个技能的 scripts/ 文件夹中附带一份 resolve_config.py 的副本，这样某人复制一个技能文件夹到任何地方都能直接工作。
• 在 SKILL.md 中记录每个配置键，让用户确切知道每个键的作用。