<!-- Generated by scripts/generate-site-content.py — do not edit by hand -->


# 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](antigravity.md) |

## 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:

```json
{ "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.

```yaml
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:

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

**Good** — an `agents.json` registry:

```json
{
  "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

```yaml
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.*