> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentgg.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage agents

> Install, inspect, and remove agents with agentgg agents, then contribute one back to the catalog.

`agentgg agents` manages the agents a scan can use: the official catalog and any agent a user adds.

## Subcommands

| Command                            | What it does                                                                                                                                               |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agentgg agents list`              | Lists installed agents. Filter with `--category`, `--mode` (`all` or `scoped`), and `--noise`. Pass `--json` for machine-readable output.                  |
| `agentgg agents info <slug>`       | Prints one agent's full metadata and prompt body as JSON.                                                                                                  |
| `agentgg agents add <file-or-dir>` | Installs a `.md` file, or every `.md` file one level inside a directory, into `~/.agentgg/agents/custom/`. Refuses to overwrite an existing slug.          |
| `agentgg agents remove <slug>`     | Removes one user-installed agent by slug. A built-in agent cannot be removed.                                                                              |
| `agentgg agents update`            | Downloads the latest official catalog into `~/.agentgg/agentgg-agents/`. Pass `--force` to re-download the current version.                                |
| `agentgg agents lint [path]`       | Checks an agent tree for duplicate slugs, a filename that matches its slug, and regex patterns that compile. Defaults to the installed official directory. |

`list` shows a category summary instead of the full table once more than 30 agents match and no filter is set. Pass `--all` to force the full table.

```
SLUG               CATEGORY   SCOPE   NOISE    DESCRIPTION
sql-injection      injection  scoped  normal   SQL built from untrusted input...
missing-auth       auth       scoped  normal   A route handler with no auth check...

2 agents
```

`SCOPE` shows `scoped` when the agent's `where` sets `extensions` or `filePatterns`, and `all` when it reviews every file.

`add` and `remove` only touch the custom directory. `remove` never searches the official catalog, so it reports a clear error for a built-in slug and never deletes the wrong file.

## Contribute an agent to the catalog

The official catalog lives at [agentgg-agents](https://github.com/agentgg-dev/agentgg-agents) on GitHub.

1. Fork the repository and branch from `main`.
2. Add or edit a `.md` file under the right category folder. The filename must match the `slug` field.
3. Test the agent against a fixture: `agentgg scan ./test-code -t ./agents/category/my-check.md`.
4. Run `agentgg agents lint .` from the repository root. A pre-commit hook runs the same check.
5. Open a pull request. The template asks for a description and test evidence.
6. A maintainer reviews the prompt quality, the false-positive risk, and the category placement.

Pull requests are squash-merged. Set `author` to your GitHub handle so it ships with the agent file: `agentgg agents info <slug>` and the raw file show it. A scan report names the agent by its slug, not its author. To select the agent in a scan afterward, see [Choose agents](/cli/guides/choose-agents).