gamealgo-cli 0.2.1 → 0.3.1

package/README.md

@@ -35,6 +35,22 @@ gamealgo docs api GameAlgo.Init --platform lua
 
 Help and documentation are fetched from the configured Server on every invocation. The CLI intentionally does not keep a documentation cache.
 
+## Agent skill
+
+Install or update the bundled GameAlgo skill for the current agent:
+
+```bash
+gamealgo skill install --agent codex
+gamealgo skill install --agent claude
+```
+
+The skill uses the project-bound CLI and live Server content. It can discover the complete iteration catalog without copied prompts:
+
+```bash
+gamealgo optimize list --json
+gamealgo optimize get ad-monetization --json
+```
+
 Adjust S2S event forwarding can be configured with an explicit event allowlist:
 
 ```bash

package/dist/client.js

@@ -177,6 +177,12 @@ export class GameAlgoAdminClient {
         const params = new URLSearchParams({ environment, platform });
         return await this.get(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/integration/plan?${params.toString()}`);
     }
+    async listOptimizationTasks() {
+        return await this.get(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/optimization/tasks`);
+    }
+    async getOptimizationTask(taskId) {
+        return await this.get(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/optimization/tasks/${encodeURIComponent(taskId)}`);
+    }
     async getAdjustMarketing(platform) {
         const query = platform ? `?platform=${encodeURIComponent(platform)}` : "";
         return await this.get(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/marketing/adjust${query}`);

package/dist/commands/optimize.js

@@ -0,0 +1,35 @@
+import YAML from "yaml";
+import { parseFlags } from "../args.js";
+import { printResult } from "../output.js";
+import { writeTextFile } from "../resources.js";
+export async function handleOptimize(client, args, global) {
+    const sub = args.shift();
+    const flags = parseFlags(args);
+    if (sub === "list") {
+        if (args.length)
+            throw new Error("usage: gamealgo optimize list [--out tasks.json]");
+        await writeOptimizationOutput(await client.listOptimizationTasks(), flags, global);
+        return;
+    }
+    if (sub === "get") {
+        const taskId = args.shift();
+        if (!taskId || args.length)
+            throw new Error("usage: gamealgo optimize get <task-id> [--out task.json]");
+        await writeOptimizationOutput(await client.getOptimizationTask(taskId), flags, global);
+        return;
+    }
+    throw new Error("usage: gamealgo optimize <list|get>");
+}
+async function writeOptimizationOutput(value, flags, global) {
+    if (flags.out) {
+        if (typeof flags.out !== "string")
+            throw new Error("--out requires a file path");
+        const content = flags.out.toLowerCase().endsWith(".json")
+            ? `${JSON.stringify(value, null, 2)}\n`
+            : YAML.stringify(value);
+        await writeTextFile(flags.out, content);
+        await printResult({ ok: true, out: flags.out }, global);
+        return;
+    }
+    await printResult(value, global);
+}

package/dist/commands/skill.js

@@ -0,0 +1,57 @@
+import { cp, mkdir, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseFlags } from "../args.js";
+import { printResult } from "../output.js";
+const SKILL_NAME = "gamealgo";
+export async function handleSkill(args, global) {
+    const sub = args.shift();
+    const flags = parseFlags(args);
+    if (sub !== "install" || args.length) {
+        throw new Error("usage: gamealgo skill install --agent <codex|claude> [--dest <skill-directory>]");
+    }
+    const destination = skillDestination(flags);
+    const updated = await pathExists(destination);
+    await installBundledGameAlgoSkill(destination);
+    await printResult({
+        ok: true,
+        skill: SKILL_NAME,
+        destination,
+        action: updated ? "updated" : "installed",
+        note: "The skill is available to new agent turns. Restart the agent if it does not appear.",
+    }, global);
+}
+export async function installBundledGameAlgoSkill(destination) {
+    const source = bundledSkillDirectory();
+    await mkdir(dirname(destination), { recursive: true });
+    await cp(source, destination, { recursive: true, force: true });
+}
+export function skillDestination(flags) {
+    if (typeof flags.dest === "string")
+        return resolve(flags.dest);
+    if (flags.dest === true)
+        throw new Error("--dest requires a directory path");
+    const agent = typeof flags.agent === "string" ? flags.agent.toLowerCase() : "";
+    if (agent === "codex") {
+        return join(process.env.CODEX_HOME || join(homedir(), ".codex"), "skills", SKILL_NAME);
+    }
+    if (agent === "claude") {
+        return join(process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude"), "skills", SKILL_NAME);
+    }
+    throw new Error("--agent must be codex or claude when --dest is not provided");
+}
+function bundledSkillDirectory() {
+    return resolve(dirname(fileURLToPath(import.meta.url)), "../../skills", SKILL_NAME);
+}
+async function pathExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}

package/dist/main.js

@@ -6,8 +6,10 @@ import { handleExperiment } from "./commands/experiment.js";
 import { handleIntegration } from "./commands/integration.js";
 import { handleGameKey } from "./commands/keys.js";
 import { handleMarketing } from "./commands/marketing.js";
+import { handleOptimize } from "./commands/optimize.js";
 import { handleReport } from "./commands/report.js";
 import { handleFileResource } from "./commands/resources.js";
+import { handleSkill } from "./commands/skill.js";
 import { loadPackageMetadata } from "./config.js";
 import { handleDocs, handleHelp } from "./docs.js";
 import { printResult } from "./output.js";
@@ -57,6 +59,10 @@ export async function main() {
             await handleAdminKey(args, global);
             return;
         }
+        if (command === "skill") {
+            await handleSkill(args, global);
+            return;
+        }
         const client = await createClient(global);
         if (command === "experiment") {
             await handleExperiment(client, args, global);
@@ -90,6 +96,10 @@ export async function main() {
             await handleMarketing(client, args, global);
             return;
         }
+        if (command === "optimize") {
+            await handleOptimize(client, args, global);
+            return;
+        }
         throw new Error(`Unknown command: ${command}`);
     }
     catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gamealgo-cli",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "GameAlgo command-line client for AI agents and game developers",
   "repository": {
     "type": "git",
@@ -16,6 +16,7 @@
   },
   "files": [
     "dist/",
+    "skills/",
     "README.md",
     "LICENSE"
   ],

package/skills/gamealgo/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: gamealgo
+description: Integrate and improve games with GameAlgo using the project-bound CLI, live Server documentation, and the Server-maintained optimization task catalog. Use when working on GameAlgo SDK setup, telemetry events, report packs, Adjust attribution, remote strategies, experiments, or when discovering supported GameAlgo iteration tasks for a game.
+---
+
+# GameAlgo
+
+Use the GameAlgo CLI as the source of current project identity and Server-maintained instructions. Do not rely on remembered SDK signatures, copied prompts, or stale local documentation.
+
+## Start In The Game Repository
+
+Run commands from the game repository that owns the integration. Before any game-level operation:
+
+1. Run `gamealgo version`. If unavailable or rejected by the Server, install the version named by the CLI or Server error.
+2. Run `gamealgo whoami --json` and confirm the project-bound `gameId`. If the project is not logged in, ask the developer for that game's Game Admin Key and run the displayed login command from the repository root.
+3. Never put `ga_admin_*` credentials in client code, logs, generated reports, commits, or chat summaries.
+
+## Discover Supported Work
+
+When the user asks what GameAlgo can do, asks for ongoing iteration, or names a broad optimization goal:
+
+1. Run `gamealgo optimize list --json` to load the complete current task catalog from the Server.
+2. Treat the result as an unranked capability catalog. Do not claim that a task is recommended or ready until its prerequisites have been checked against the current game.
+3. Once the user selects a task, or their request clearly identifies one, run `gamealgo optimize get <task-id> --json`.
+4. Read each topic named in the task's `docs` field with `gamealgo docs <topic>` before implementation.
+5. Follow the returned `agentSteps` and use `deliverables` as the completion checklist.
+
+Do not run every catalog task in sequence. Complete the selected task and report unmet prerequisites instead of manufacturing missing data.
+
+## Route Work To Required Documentation
+
+Classify the requested work by the actions it requires, not only by the user's task title. Before implementation or interpreting results, load every applicable source below from the current Server:
+
+- SDK installation, identity, lifecycle, telemetry, attribution, advertising, or purchase work: run `gamealgo integration get-plan --environment <domestic|overseas> --platform <ios|android|maker|rest> --json`, then read `gamealgo docs sdk-integration`.
+- Calling or changing a concrete public SDK function: additionally run `gamealgo docs api <function> --platform <platform>` for each affected function. Never infer one platform's API from another.
+- Adding or changing events: additionally run `gamealgo events list --days 30 --json` before defining fields or names.
+- Reading, creating, changing, previewing, or publishing Report Packs, charts, report SQL, or business metrics: read `gamealgo docs reports` before interpreting data or editing definitions.
+- Creating or changing remote configuration, strategies, experiments, variants, objectives, rollout, or assessment: read `gamealgo docs experiments`; also load the integration plan and exact API documentation when client code changes.
+- Adjust or marketing attribution work: load the selected optimization task when one applies, read every topic in its `docs`, and load the integration plan and exact identifier/attribution APIs for the target platform.
+
+If work crosses domains, combine their requirements. For example, an advertising event used by an experiment report requires the integration plan, event inventory, SDK API documentation, report documentation, and experiment documentation. Read a topic once per turn unless the task expands or the Server documentation version changes.
+
+## Follow Mandatory Checkpoints
+
+1. Confirm project identity, environment, platform, requested outcome, and available permissions.
+2. Load the required live documents and task detail before making implementation decisions.
+3. Inspect existing code, configuration, event inventory, Report Pack, or experiment state before editing. Reuse established project patterns and preserve local fallback behavior.
+4. Make the smallest coherent change and run local validation, Report Pack validation, previews, or dry runs supported by the current workflow.
+5. Before publishing reports, remote configuration, scripts, strategies, experiments, rollout changes, or other externally visible mutations, show the relevant diff and impact unless the user has already explicitly authorized that exact operation.
+6. After execution, verify with real configuration retrieval, accepted non-debug events, report results, or experiment state as appropriate. A code diff or successful request alone is not business verification.
+
+Reading documentation does not grant permission to mutate production. CLI and Server validation, scopes, project binding, and explicit approval requirements still apply.
+
+## Integration Details
+
+For SDK integration or telemetry changes, determine the actual deployment environment and runtime platform, then run:
+
+```bash
+gamealgo integration get-plan --environment <domestic|overseas> --platform <ios|android|maker|rest> --json
+```
+
+Inspect the existing project before editing. Reuse existing SDK wrappers, user identity, lifecycle, event, advertising, purchase, and attribution flows.
+
+Reuse events with the same business meaning, register new fields with their real JSON types, and verify non-debug context and business events with real runtime traffic.
+
+## Changes And Verification
+
+- Make repository changes when the selected task requires them; keep unrelated files unchanged.
+- Do not push directly to a protected primary branch. Follow the repository's branch and merge-request workflow.
+
+Finish with the live documentation and task detail consulted, changed files, checks executed, observed data evidence, unmet prerequisites, and any operation still awaiting developer approval. Only call initial integration activated after real configuration and event acceptance checks pass.

package/skills/gamealgo/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "GameAlgo"
+  short_description: "接入 GameAlgo 并执行服务端维护的游戏优化任务"
+  default_prompt: "Use $gamealgo to inspect this game and load the current GameAlgo task catalog."
+
+policy:
+  allow_implicit_invocation: true