---
name: ags-extend
description: "AccelByte Extend — custom server-side game logic on AGS. Use for choosing an Extend pattern (Override, Event Handler, Service Extension), scaffolding a service, deploying to AGS, running locally, testing, and debugging."
allowed-tools: Bash Read Write Edit Glob
model: sonnet
---

# AGS Extend

Single entry point for the full Extend lifecycle. **This file is a router.** It reads the user's invocation, picks exactly one subskill, hands control to it, and otherwise stays out of the way.

Before running this skill, apply `accelbyte` when it is available.

Use the tool selection and fallback policy from `accelbyte` after routing to a subskill; do not redefine it here.

<!-- Authoring boundary: AGS CLI is intentionally not recommended as a fallback in this skill because it does not cover the full Extend Helper CLI lifecycle. Keep user-facing fallback guidance within the Extend-owned tool boundary until that parity exists. -->

Never answer Extend questions, scaffold templates, run CLI commands, or apply patches from this file. All of that belongs inside a subskill.

## Subskills

| #  | Subskill | Phase | Purpose | Depends on |
|----|---|---|---|---|
| 1  | `subskills/ask.md` | any | Conceptual questions: what Extend is, pattern selection, comparisons | — |
| 2  | `subskills/design.md` | design | Multi-app project shaping: which patterns + how they fit together (read-only) | — |
| 3  | `subskills/wizard.md` | scaffold | Interview → clone template → apply integration patches | design (optional) |
| 4  | `subskills/install-dep.md` | scaffold | Detect runtimes; install per-app project deps | wizard (typically) |
| 5  | `subskills/install-cli.md` | scaffold | Install `extend-helper-cli` (required before deploy) | — |
| 6  | `subskills/install-mcp.md` | scaffold | Wire Extend MCP servers into the user's AI IDE (optional) | — |
| 7  | `subskills/init.md` | scaffold | Orchestrates wizard + install-dep + install-cli + optional install-mcp | — |
| 8  | `subskills/proto.md` | scaffold/build | Regenerate proto-derived code after contract or SDK changes | wizard |
| 9  | `subskills/debug.md` | build | Run and test a local Extend app | wizard, install-dep |
| 10 | `subskills/test.md` | build | Write or run unit / integration / contract tests | wizard, install-dep |
| 11 | `subskills/deploy.md` | ship | Build-push + deploy one or more apps to AGS | wizard, install-cli |
| 12 | `subskills/ci.md` | ship | Wire `image-upload` + `deploy` into GitHub Actions or GitLab CI | deploy |
| 13 | `subskills/observe.md` | operate | Pull logs, health, and runtime signals for a deployed app | deploy |
| 14 | `subskills/doctor.md` | operate | Read-only diagnosis: symptoms → likely causes → next-step pointer | — |
| 15 | `subskills/upgrade.md` | operate | Guided SDK or proto contract version bump with breakage surfacing | deploy (recommended) |

Phases run roughly in order but loop (design → scaffold → build → ship → operate → back to design/build). `ask` and `doctor` are phase-free: `ask` answers concept questions at any time; `doctor` diagnoses without mutating anything and hands off to the subskill that owns the fix.

## Routing

<tool_usage_rules>

1. Resolve the invocation to **exactly one** subskill using the decision procedure below.
2. Read that subskill file start to finish before taking any action. Do not answer from memory of a subskill's contents — subskills change, and the file on disk is the source of truth.
3. Do not mix instructions across two subskills in one response. If a handoff is needed, finish the current subskill, then tell the user which one to invoke next.
4. If the user's message spans multiple phases ("scaffold and deploy"), route to the earliest phase and announce the next step; do not auto-chain into the next subskill.
5. Use only the tools listed in frontmatter. Subskills may further restrict; respect their restrictions.

</tool_usage_rules>

### Decision procedure

Apply these checks in order. Stop at the first match.

1. **Is the message off-topic?** (General AGS admin, non-Extend AccelByte SDKs, unrelated programming help.) → Decline with the off-topic response (below). Do not route.
2. **Is the message empty or only `/ags-extend`?** → Ask the disambiguation question (below). Do not route yet.
3. **Is there a direct subskill cue?** (Table below.) → Route to that subskill.
4. **Is the message conceptual** ("what", "how does", "which", "should I", "vs")? → Route to `ask`.
5. **Does the message span multiple phases?** → Route to the earliest phase; announce the later steps as follow-ups.
6. **No match** → Ask the disambiguation question.

### Cue table

First match wins. Cues are case-insensitive substring matches unless noted.

| Cue | Route |
|---|---|
| `ask`, "what is", "which pattern", "how does", "should I use", "vs", "compared to" | `subskills/ask.md` |
| `design`, "multi-app", "how should I structure", "which patterns do I need", "project shape", "how do the pieces fit" | `subskills/design.md` |
| `init`, "set up everything", "from scratch", "bootstrap", "start a new project" | `subskills/init.md` |
| `wizard`, "new project" (without "set up everything"), "scaffold", "generate", "build me a" | `subskills/wizard.md` |
| `install-dep`, "install dependencies", "go mod tidy", "pip install", "restore packages" | `subskills/install-dep.md` |
| `install-cli`, "extend-helper-cli", "install cli" | `subskills/install-cli.md` |
| `install-mcp`, "mcp setup", "mcp server", "hook up ides", IDE name + "mcp" | `subskills/install-mcp.md` |
| `proto`, "regen proto", "regenerate proto", "buf generate", "make proto", "proto contract changed" | `subskills/proto.md` |
| `debug`, "run locally", "test locally", "local server", "localhost" | `subskills/debug.md` |
| `test`, "unit test", "integration test", "run tests", "write a test", "coverage" | `subskills/test.md` |
| `deploy`, "push", "ship", "release", "image-upload" | `subskills/deploy.md` |
| `ci`, "github actions", "gitlab ci", "pipeline", "workflow file", "automate deploy" | `subskills/ci.md` |
| `observe`, "logs", "live status", "health check", "monitor", "degraded", "why is it crashing" | `subskills/observe.md` |
| `doctor`, "diagnose", "what's wrong", "something is off", "not sure what's broken", "help me narrow this down" | `subskills/doctor.md` |
| `upgrade`, "bump sdk", "new sdk version", "upgrade sdk", "migrate to v2", "dependency upgrade" | `subskills/upgrade.md` |

### Disambiguation prompt

Use verbatim when no cue matches and the user hasn't typed anything specific:

> I can help with Extend across the full lifecycle:
> • **ask** — what is it, which pattern, how it works
> • **design** — shape a multi-app project before scaffolding
> • **init** — scaffold a new project from scratch
> • **debug** — run it locally
> • **test** — unit / integration / contract tests
> • **deploy** — ship to AGS
> • **ci** — wire deploys into GitHub Actions / GitLab CI
> • **observe** — logs and health for a deployed app
> • **doctor** — read-only diagnosis when something's off
> • **upgrade** — guided SDK or proto version bump
>
> Which one? (Or describe the symptom / goal and I'll pick.)

Then wait for the user's reply. Do not guess.

### Chained intents

When the user describes multiple phases in one message:

- "Scaffold a matchmaking override and deploy it" → route to `init` (scaffold phase). After the subskill finishes, tell the user: "Run `/ags-extend deploy` when you're ready to ship."
- "Fix the bug and redeploy" → route to `debug` first (investigate + fix locally), then point at `deploy`.
- "Why is it failing and how do I restart it" → route to `observe` first (diagnose), then point at `deploy`.
- "Design a tournaments product and generate the apps" → route to `design` first (shape the system), then point at `init`.
- "It's broken — diagnose and fix" → route to `doctor` first (read-only narrow-down), then point at whatever subskill owns the fix (`debug`, `deploy`, `upgrade`).
- "Bump the SDK and redeploy" → route to `upgrade` first, then point at `deploy` once the bump is green.

Never invoke a second subskill automatically. The user should see one subskill run per invocation so they can stop if something goes wrong mid-chain.

### Off-topic response

Use when the message isn't about Extend:

> This skill covers AccelByte Extend specifically (Overrides, Event Handlers, Service Extensions). For general AGS admin, non-Extend SDK work, or other AccelByte products, check the AccelByte docs or Admin Portal. I won't route to a subskill for this.

### When subskills conflict

If the user's follow-up inside a running subskill clearly belongs to a different subskill (e.g. during `deploy`, they ask "actually how do the three patterns differ?"), finish answering the narrow question if it's a 1-sentence sidebar, or stop the current subskill and say:

> That's an `ask` question. Stop here and run `/ags-extend ask` to go deeper, or tell me to continue `deploy`.

## Hard rule: cite-or-defer for `extend-helper-cli`

`extend-helper-cli` command names, flags, and environment variables hallucinate easily. To prevent this, the skill enforces one rule that supersedes every subskill's local guidance:

**`references/deploy/cli-commands.md` is the single authoritative source for CLI syntax.** Every subskill that mentions a CLI command, flag, or env var must defer to that file — by linking to it ("see `references/deploy/cli-commands.md`") or by reading it before quoting any CLI invocation. Restating CLI flags from memory anywhere else in this skill is a defect, even if the restatement happens to be correct.

Subskills that touch the CLI (deploy, debug, observe, ci, install-cli, doctor, upgrade) must include this in their `<grounding_rules>`:

> Before writing any `extend-helper-cli <subcommand>` invocation in a response or example, Read `references/deploy/cli-commands.md`. Do not restate flags from memory. If `cli-commands.md` doesn't document the flag you want to use, the flag does not exist — use a documented alternative, surface the gap to the user, or stop and ask.

The "What the CLI does NOT have" section of `cli-commands.md` explicitly catalogues invented flags so they can be recognized as red flags during authoring or runtime.

## Project layout: per-app, no project-wide manifest

There is no project-wide manifest file. Each Extend app is a standalone directory cloned from an AccelByte template (Go, C#, Python, Java — see `references/init/templates.md`) and carries its own:

- `Makefile` — wraps Docker-based build + proto regen
- `Dockerfile` — multi-stage build (proto-builder → builder → runtime)
- `.env.template` (or `.env` — a copy for local use) — per-app credentials and config
- `.devcontainer/` — optional VS Code devcontainer with the toolchain pre-installed
- `IMPLEMENTATION_PLAN.md` (after `/ags-extend wizard`) — the agreed plan

**Multi-app projects** are just multiple of those directories side by side, typically inside one git repo. Subskills discover the active app by locating a `Makefile` + `Dockerfile` in the working directory or one level up — never by reading a project-level config file (skill-internal discovery heuristic, not an AGS contract).

`references/init/manifest-schema.md` documents a forward-looking proposal for a project-wide `extend-project.yaml`. **No subskill should generate it today**, and references in this skill bundle have been updated to reflect per-app discovery.

## What this file does NOT do

- **Does not explain Extend concepts.** That's `ask`.
- **Does not run any CLI commands.** Those live in `deploy`, `debug`, `observe`, `install-cli`.
- **Does not read references.** Subskills own their own reading.
- **Does not carry state across invocations.** Each `/ags-extend` call is fresh; the only state is what's on disk (the app's `Makefile`, `Dockerfile`, `.env`, `IMPLEMENTATION_PLAN.md`, etc.), and the relevant subskill reads it.