feat: publish Claude and NPX AI agent marketplace plugins (#1334)

Signed-off-by: Guillaume Belanger <guillaume.belanger27@gmail.com>

Author: gruyaume

.claude-plugin/marketplace.json

@@ -0,0 +1,27 @@
+{
+  "name": "ellanetworks-core",
+  "owner": {
+    "name": "Ella Networks",
+    "email": "contact@ellanetworks.com"
+  },
+  "metadata": {
+    "description": "Official Ella Networks plugins for Claude Code",
+    "version": "0.2.0"
+  },
+  "plugins": [
+    {
+      "name": "ella-core",
+      "description": "Manage and inspect a running Ella Core 5G private mobile network via its REST API. Triggers: subscribers, profiles, slices, policies, data networks, radios, BGP, NAT, routes, PDU sessions, IMSI, S-NSSAI, DNN, 5QI, AMBR, ARP, audit logs, flow reports, data usage on an Ella Core instance.",
+      "version": "0.2.0",
+      "source": "./",
+      "author": {
+        "name": "Ella Networks",
+        "email": "contact@ellanetworks.com"
+      },
+      "homepage": "https://docs.ellanetworks.com",
+      "repository": "https://github.com/ellanetworks/core",
+      "license": "Apache-2.0",
+      "keywords": ["5g", "mobile-network", "private-5g", "ella-core", "ellanetworks"]
+    }
+  ]
+}

.claude-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "ella-core",
+  "version": "0.2.0",
+  "description": "Manage and inspect a running Ella Core 5G private mobile network via its REST API.",
+  "author": {
+    "name": "Ella Networks",
+    "email": "contact@ellanetworks.com"
+  },
+  "homepage": "https://docs.ellanetworks.com",
+  "repository": "https://github.com/ellanetworks/core",
+  "license": "Apache-2.0",
+  "keywords": ["5g", "mobile-network", "private-5g", "ella-core", "ellanetworks"]
+}

.github/skills/ella-core-api/SKILL.md

@@ -15,7 +15,26 @@ Before using the skill, you need:
 
 ## 1. Install the skill
 
-Download [`SKILL.md`](https://raw.githubusercontent.com/ellanetworks/core/main/.github/skills/ella-core-api/SKILL.md) and place it in a skills directory that your AI tool can discover (e.g. `<project>/.agents/skills/ella-core-api/SKILL.md`).
+=== "Claude Code"
+
+    ```
+    /plugin marketplace add ellanetworks/core
+    /plugin install ella-core@ellanetworks-core
+    ```
+
+    Refresh later with `/plugin marketplace update`.
+
+=== "NPX"
+
+    Works with any Skills-aware tool that auto-discovers `.agents/skills/` (Codex, Cursor, Cline, Goose, Amp, OpenCode, …).
+
+    ```
+    npx skills add ellanetworks/core
+    ```
+
+=== "Manual"
+
+    Copy the [`skills/ella-core/`](https://github.com/ellanetworks/core/tree/main/skills/ella-core) folder into the skills directory your AI tool discovers.
 
 ## 2. Prompt the agent
 

docs/how_to/ai_agents.md

@@ -0,0 +1,95 @@
+---
+name: ella-core
+description: >
+  Manage and inspect a running Ella Core 5G private mobile network via its REST API.
+  Use when the user asks to provision, update, list, inspect, or delete subscribers,
+  profiles, slices, policies, data networks, radios, routes, BGP peers, NAT, operators,
+  or users; or asks about live status, data usage, flow reports, audit logs, AMF/SMF/UPF
+  state, PDU sessions, gNB connections, IMSIs, S-NSSAIs, DNNs, 5QI, AMBR, ARP, or any
+  runtime telemetry of an Ella Core instance.
+metadata:
+  version: 0.2.0
+  author: ellanetworks
+---
+
+# Ella Core Skill
+
+Ella Core is a 5G private mobile network packaged as a single Go binary (AMF + SMF + UPF + AUSF). This skill operates a running instance via its REST API.
+
+## Connection
+
+Two values are required:
+
+- **Base URL** — e.g. `http://192.168.1.10:5000`. Read from `ELLA_CORE_URL` if set.
+- **API token** — string prefixed with `ellacore_`. Read from `ELLA_CORE_TOKEN` if set.
+
+Ask the user for any value that is not in the environment or earlier in the conversation. Token minting and roles: `references/auth.md`.
+
+Authenticate every request with `Authorization: Bearer $ELLA_CORE_TOKEN`. Exceptions (no auth required): `GET /api/v1/status`, `GET /api/v1/metrics`, `GET /api/v1/openapi.yaml`.
+
+Ella Core typically serves HTTPS with a self-signed certificate. Use `curl -k` (or `--cacert <file>` if the user provides one) for `https://` URLs. Plain HTTP works against `h2c` instances.
+
+## Calling the API
+
+Use `curl -sk` (silent + skip cert verification) and pipe JSON through `jq` (or `python3 -m json.tool`):
+
+```bash
+curl -sk -H "Authorization: Bearer $ELLA_CORE_TOKEN" \
+  "$ELLA_CORE_URL/api/v1/subscribers?per_page=100" | jq
+```
+
+**Retrieval-first.** Before calling any endpoint not already used in this session, check `references/examples.md` for a recipe. If the operation isn't covered, fetch the OpenAPI spec — the source of truth, never guess paths or shapes:
+
+```bash
+curl -s "$ELLA_CORE_URL/api/v1/openapi.yaml"
+```
+
+Fetch once per session and reuse. Don't pre-fetch resource lists unless you need their IDs — aggregate endpoints often return everything in one call.
+
+## Endpoint namespacing
+
+Many resources live under sub-paths — never assume top-level. Common groups:
+
+- `/api/v1/auth/*` — login, logout, refresh, lookup-token
+- `/api/v1/networking/*` — data-networks, routes, NAT, BGP, interfaces
+- `/api/v1/ran/*` — radios, events
+- `/api/v1/logs/audit` — audit logs
+- `/api/v1/operator/*` — operator code, ID, home-network-keys, NAS security
+- `/api/v1/cluster/*` — HA cluster management
+- `/api/v1/subscribers`, `/api/v1/profiles`, `/api/v1/policies`, `/api/v1/slices` — top-level
+- `/api/v1/subscriber-usage`, `/api/v1/flow-reports` — top-level
+
+When in doubt, fetch the OpenAPI spec.
+
+## Response envelope
+
+- Success: `{"result": <payload>}`
+- Error: `{"error": "message"}`
+- Mutation success (201/200): `{"result": {"message": "..."}}`
+
+## Pagination
+
+List endpoints accept `page` (default 1) and `per_page` (default 25, max 100). Responses include `items`, `page`, `per_page`, `total_count`. Use `per_page=100` when iterating to minimize round-trips.
+
+## Mutations and destructive operations
+
+For any `POST`, `PUT`, `PATCH`, or `DELETE`:
+
+1. **Confirm with the user first.** State what will change and ask for explicit approval. Do not chain destructive calls without re-confirming.
+2. **List or GET before delete.** Confirm the target exists and show its current state to the user.
+3. **Verify prerequisites before create.** Resources follow a strict dependency chain (data network → slice → profile → policy → subscriber). See `references/data-model.md`.
+4. **One change at a time.** Don't bundle unrelated mutations. Re-read state after each one to confirm it landed.
+
+## When to load references
+
+| File | Read when |
+|------|-----------|
+| `references/auth.md` | Setting up tokens, hitting 401/403, reasoning about RBAC |
+| `references/data-model.md` | Provisioning new resources or explaining the data model |
+| `references/conventions.md` | Questions about IMSI, K/OPc, 5QI, ARP, AMBR, bitrate strings, byte conversion, BGP/NAT specifics |
+| `references/examples.md` | Looking for a recipe before fetching the full OpenAPI |
+| `references/troubleshooting.md` | A request fails or returns unexpected data |
+
+## External documentation
+
+For non-API guidance, fetch from `https://docs.ellanetworks.com/` — for example `how_to/ai_agents/`, `how_to/backup_and_restore/`, or `reference/`.

skills/ella-core/SKILL.md

@@ -0,0 +1,44 @@
+# Authentication
+
+## Token types
+
+- **JWT session tokens** — issued by `POST /api/v1/auth/login` for browser/UI sessions. Short-lived; refreshed at `POST /api/v1/auth/refresh`. Not appropriate for agents.
+- **API tokens** — long-lived, prefixed `ellacore_`. Use these for agents and automation. They inherit the role of the owning user.
+
+Mint API tokens in the UI under **Users → API Tokens**, or via the API:
+
+- `POST /api/v1/users/me/api-tokens` — for the calling user
+- `POST /api/v1/users/{email}/api-tokens` — admin-only, for another user (path parameter is the user's **email**, not an ID)
+
+Identify the calling user with `GET /api/v1/users/me`.
+
+## Roles and permissions
+
+Three roles:
+
+| Role | ID | Can |
+|------|----|-----|
+| Admin | 1 | All endpoints, including user/operator management |
+| Read-Only | 2 | Read-only access to all resources |
+| Network Manager | 3 | Manage subscribers, profiles, policies, slices, data networks; read all telemetry |
+
+Permissions are strings of the form `<resource>:<action>`, checked per endpoint. A 403 means the token's role lacks the required permission — switch to a higher-privilege token rather than retrying.
+
+Notable privileged permission: `subscriber:read_credentials` (used by `GET /api/v1/subscribers/{imsi}/credentials`) is granted only to Admin and Network Manager.
+
+## Environment variables
+
+The skill expects:
+
+- `ELLA_CORE_URL` — base URL with no trailing slash (e.g. `http://192.168.1.10:5000`)
+- `ELLA_CORE_TOKEN` — full API token including the `ellacore_` prefix
+
+If either is unset, ask the user before making any call.
+
+## Unauthenticated endpoints
+
+These do not require a token:
+
+- `GET /api/v1/status` — health and version
+- `GET /api/v1/metrics` — Prometheus metrics
+- `GET /api/v1/openapi.yaml` — full OpenAPI 3.1 specification

skills/ella-core/references/auth.md

@@ -0,0 +1,43 @@
+# Field formats and valid values
+
+## Identifiers
+
+- **IMSI** — 15-digit string, e.g. `"999016992280505"`. In `CreateSubscriberParams`, the field is `imsi`. Must start with the operator's MCC+MNC.
+- **Permanent key (K)** — 32-character hex string. **Field name in the API is `key`** (not `K`).
+- **OPc** — 32-character hex string. **Field name in the API is `opc`** (lowercase). Optional on create — derived from operator code if omitted.
+- **Sequence number** — 6-byte hex string. **Field name in the API is `sequenceNumber`** (camelCase, unlike most other fields which are snake_case).
+
+## QoS
+
+- **5QI** — valid values: `5, 6, 7, 8, 9, 69, 70, 79, 80`
+- **ARP** — integer, range `1-15`
+- **AMBR / session bitrate** — string with unit, e.g. `"50 Mbps"`, `"1 Gbps"`, `"500 Kbps"`
+
+## Dates
+
+- Usage queries — `YYYY-MM-DD`
+
+## Subscriber usage
+
+`GET /api/v1/subscriber-usage` **requires** the `group_by` query parameter (`day` or `subscriber`); omitting it returns 400. Optional: `start`, `end` (defaults: 7 days ago → today), `subscriber` (IMSI filter).
+
+Response is `{"result": [<single-key objects>]}` — each object's key is a date (when `group_by=day`) or an IMSI (when `group_by=subscriber`); the value is a `{uplink_bytes, downlink_bytes, total_bytes}` summary.
+
+## Byte counts and presentation
+
+Usage byte fields are `uplink_bytes`, `downlink_bytes`, `total_bytes` (int64). Convert to binary units before presenting:
+
+- MiB = bytes / 1,048,576
+- GiB = bytes / 1,073,741,824
+
+Round to one decimal place with the unit suffix (e.g. `46.2 MiB`, `1.3 GiB`). Verify `uplink_bytes + downlink_bytes == total_bytes` before presenting.
+
+## BGP and NAT
+
+- BGP supports up to **5 peers** (`/api/v1/networking/bgp/peers`).
+- BGP global state at `/api/v1/networking/bgp` includes `enabled`, `localAS`, `routerID`, `listenAddress`, and `rejectedPrefixes`.
+- NAT status at `/api/v1/networking/nat` returns `{"enabled": bool}`. When NAT is enabled, the BGP speaker runs but does **not** advertise subscriber routes.
+
+## Flow reports
+
+`/api/v1/flow-reports` — filterable by subscriber, protocol, source, and destination. Includes both allowed and dropped flows. `/api/v1/flow-reports/stats` returns top protocols and top destination IPs (no required parameters).