antigravity-config-json-valid¶

Antigravity registry files must decode their paths and filters correctly


Severity	error (disabled)
Autofix	-
Since	v0.20.0
Repo Types	antigravity, antigravity-plugin
Category	Google Antigravity

Why¶

A customization root can carry registry files — agents.json, plugins.json, skills.json, workflows.json — that name where else to load that kind of customization from. They hold no customizations themselves. These files accept JSONC: line and block comments and trailing commas. Registry discovery and this opt-in validator use the same syntax:

{ "entries": [{ "path": "internal/schedule/agents" }] }

Measured against agy 1.1.25 and 1.1.26: a registry whose root is neither an object nor null logs one Failed to load JSON config file line and is skipped, and agy exits 0. Nothing else reports it, so a mistyped registry looks exactly like a project that has none — the agents or skills it was meant to add are simply absent.

Opt-in¶

Off by default. Only agents.json and plugins.json could be exercised against a running agy: no offline subcommand loads the other two, so the checks stop at what a measurement covers rather than guessing at a schema. Turn it on when a repository actually uses these files.

rules:
  antigravity-config-json-valid:
    enabled: true

Severity¶

Errors — the registry is skipped and loads nothing:

Invalid JSONC, including single-quoted strings or unquoted keys, or a non-finite number (NaN, Infinity, -Infinity).
A UTF-8 byte-order mark (BOM). Remove it; the loader does not strip it.
A non-null root that is not a JSON object.
Non-null entries or inherits that is not an array.
A non-null element of either array that is not an object, or a non-null path that is not a string.
Non-null include_only or exclude that is not a string array, or a non-null array element that is not a string.

One finding groups field type errors and names the first few positions. A type error remains fatal even if a later duplicate replaces the field.

What is not reported¶

Whether a path resolves. A path is absolute, ~/-relative, or relative to the repository root, and a registry may legitimately name a directory that only exists on a developer's machine.

skillsaw still follows the ones that do resolve inside the repository. A plugins.json entry's plugins get their hooks, MCP servers, skills and prose linted, and an agents.json entry's *.md is read as agent prose — independently of this rule, which is opt-in. include_only and exclude are ignored when deciding what to lint: skillsaw reports what a repository ships, not what it currently loads. - Unknown keys. Antigravity reads these files with a tolerant JSON decoder that discards them. - Field casing. Known fields match case-insensitively: Entries, Inherits, Path, Include_Only and EXCLUDE are accepted. Underscores remain significant; IncludeOnly is an ignored unknown field. - Repeated fields. Later path strings replace earlier strings; null retains a prior string. Repeated nonempty entries / inherits arrays reuse corresponding path-entry fields, including after shortening and regrowing the array. An empty array or null resets those entries. Discovery follows the resulting paths, using this same decoded view. - Null defaults. A null root, null arrays, null entries and missing or null paths are accepted. An entry without a path contributes nothing; valid siblings still load. Null filter elements are accepted too. - An empty string path. It contributes no directory. - A large finite JSON number in an unknown field. The loader ignores that field; the lexical tokens NaN and Infinity remain invalid.

Examples¶

Bad — an array root, which Antigravity skips whole:

[{ "path": "internal/schedule/agents" }]

Good — an agents.json registry:

{
  "entries": [
    {
      "path": "internal/schedule/agents",
      "include_only": ["gtfs-*"]
    }
  ],
  "inherits": [{ "path": "tools/shared/agents.json" }]
}

inherits names another registry file, not a directory: a directory there loads nothing.

How to fix¶

Wrap the list in an object under entries.
Give every entry a string path. What it may name depends on the registry: for agents.json it must be the directory the items sit directly inside, and a parent of that loads nothing. For plugins.json either spelling works — one plugin directory, or a container whose direct children are plugins.
skills.json and workflows.json have shape-only coverage. Their loading semantics remain unverified, and skillsaw does not resolve their entries.

Configuration¶

rules:
  antigravity-config-json-valid:
    enabled: false  # true | false | auto
    severity: error

Run skillsaw explain antigravity-config-json-valid to see this documentation and the rule's effective configuration in your terminal.