---
name: grix-admin
description: Grix agent administration through the `grix_admin` tool — create remote API agents, manage agent categories, rotate API keys — and bind an agent's remote parameters into the local grix-connector config with reload and verification. For "create me an agent for X" requests, run `grix-egg` discovery first; use this skill when the user already has agent parameters to bind, asks for category management, or grix-egg found no matching egg / the user wants a blank agent.
trigger: When the user wants to bind an existing agent's parameters into the local grix-connector, list / create / update / assign agent categories, or create a blank agent after grix-egg discovery found nothing suitable
---

# Grix Agent Admin

Three workflows. A request may name one on its first line
(`connector-bind-local`, `create-and-connector-bind`, `category-manage`);
otherwise pick the one that matches the ask.

| Workflow | What it does |
|---|---|
| [`connector-bind-local`](#workflow-a--connector-bind-local) | Write an existing remote agent's parameters into local `agents.json`, reload, verify |
| [`create-and-connector-bind`](#workflow-b--create-and-connector-bind) | Create a remote agent via `grix_admin`, then run `connector-bind-local` |
| [`category-manage`](#workflow-c--category-manage) | List / create / update / assign categories via `grix_admin` |

**Creating a new agent from a business description?** Run the `grix-egg` skill
first (search the egg market, let the owner hatch a ready-made egg). Come here
for creation only when no egg matched or the user explicitly wants a blank
agent — and say so in your reply.

All remote operations go through the `grix_admin` tool on the current
account's WS channel — never hand-written HTTP or scripts, never across
accounts, and never ask the user for a website account or password.

## `grix_admin` actions

Always pass `action` explicitly:

| `action` | Required | Optional |
|---|---|---|
| `create_agent` | `agentName`, `introduction` | `isMain`, `categoryId`, `categoryName`, `parentCategoryId`, `categorySortOrder` |
| `list_categories` | — | — |
| `create_category` | `name`, `parentId` | `sortOrder` |
| `update_category` | `categoryId`, `name`, `parentId` | `sortOrder` |
| `assign_category` | `agentId`, `categoryId` (`0` clears) | — |
| `rotate_api_key` | `agentId` | — |

Notes:

- `categoryId` and `categoryName` are mutually exclusive — report the conflict
  and stop if both are given.
- With `categoryName`, the backend looks for an exact match under
  `parentCategoryId`, creating it if absent. If several exact matches exist,
  stop and ask the owner for an explicit `categoryId`.
- `isMain=true` only when actually creating a new main API agent.
- `code=4003` means a missing scope — report the exact `agent.api.create` or
  `agent.category.*` scope.

## Agent creation intake (before any `create_agent`)

1. `agentName` and `introduction` must both be present and specific. Never
   create an agent with an empty, generic, or placeholder introduction.
2. If either is missing or vague, ask one concise question in the user's
   language: what does this agent mainly do — core responsibilities, whom it
   serves, and its boundaries?
3. Turn the answer into a concise professional `agentName` and an
   `introduction` that states purpose, core responsibilities, intended users or
   scenarios, operating expectations, and boundaries. Treat `introduction` as
   the agent's behavioral specification, not marketing copy.
4. Preserve the user's facts and intent; do not invent permissions, authority,
   or expertise they did not grant.

## Workflow A — `connector-bind-local`

Inputs: `agent_name`, `agent_id`, `api_endpoint`, `api_key` (all required);
`client_type` (optional, default `pi`). Missing field → say which and stop.

1. Target file `~/.grix/config/agents.json`; initialize a missing file or
   directory as `{ "agents": [] }`.
2. Before writing, back it up to
   `~/.grix/config/agents.json.bak.<YYYYMMDDHHMMSS>`.
3. Find the entry whose `name` equals `agent_name`: update it in place, or
   append. Write `name`, `ws_url` (= `api_endpoint`), `agent_id`, `api_key`,
   `client_type`.
4. Keep the JSON valid; set both the file and the backup to mode `0o600`.
5. If the daemon is running, reload through the synchronous Admin API (not
   the CLI): `POST http://127.0.0.1:19580/api/reload`; a custom port is in
   `~/.grix/data/admin-port`. On error, report it and stop.
6. Verify via `GET /api/agents` that the entry exists with `alive=true`.
7. `alive=true` only proves the instance started. Also check the platform
   connection — the latest daemon log for WebSocket success or auth failure,
   or ask the owner to send a test message.

Reporting: state each phase (config write, reload, `alive=true`, platform
connection) separately. If the platform check fails or cannot be run, say so
explicitly ("config loaded and instance started, platform connection not
verified") — never claim full convergence without it. Never echo the full
`api_key` in plaintext.

## Workflow B — `create-and-connector-bind`

Inputs: `agentName`, `introduction` (required; run the intake above);
`isMain`, `clientType` (default `pi`), `categoryId` | `categoryName`,
`parentCategoryId` (default `0`), `categorySortOrder` (optional).

1. Call `grix_admin` once with `action=create_agent` and the supplied fields.
2. Read `createdAgent.id`, `agent_name`, `api_endpoint`, `api_key` from the
   result. If a requested category was not applied, finish it with the
   category actions.
3. Continue immediately with Workflow A using those values and `clientType`.
4. Report remote creation and local binding as separate phases; if binding
   fails after creation succeeded, report the overall result as partial.

Fallback: if no agent parameters exist and the current account lacks
`agent.api.create`, stop and ask the owner to create the agent in the backend
admin, then run Workflow A with the parameters they provide.

## Workflow C — `category-manage`

Inputs: `operation` (`list` | `create` | `update` | `assign`) plus the fields
required by the matching action above. Map directly to `list_categories`,
`create_category`, `update_category`, `assign_category`. If the request also
creates an agent, use Workflow B instead.

## Reference

[references/api-contract.md](references/api-contract.md) — request/response
shapes for each action and the local binding field mapping.