@bitget-ai/getagent-skill 0.2.1

package/.claude-plugin/marketplace.json

@@ -0,0 +1,28 @@
+{
+  "name": "getagent-skills",
+  "owner": {
+    "name": "GetAgent",
+    "email": "support@bitget.com"
+  },
+  "metadata": {
+    "description": "Official GetAgent Agent Skill for trading Playbook authoring",
+    "version": "0.2.1"
+  },
+  "plugins": [
+    {
+      "name": "getagent",
+      "source": "./",
+      "description": "Create, validate, upload, backtest, publish, and enable GetAgent quantitative trading Playbooks.",
+      "version": "0.2.1",
+      "author": {
+        "name": "GetAgent",
+        "email": "support@bitget.com"
+      },
+      "repository": "git@gitlab.bitget.tools:algorithm/upex-algorithm-getall-skill-sdk.git",
+      "license": "Proprietary",
+      "keywords": ["getagent", "trading", "playbooks", "backtesting", "agent-skills"],
+      "category": "external-integrations",
+      "tags": ["trading", "backtesting", "agent-skills", "playbooks"]
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "getagent",
+  "version": "0.2.1",
+  "description": "Create, validate, upload, backtest, publish, and enable GetAgent quantitative trading Playbooks.",
+  "author": {
+    "name": "GetAgent",
+    "email": "support@bitget.com"
+  },
+  "repository": "git@gitlab.bitget.tools:algorithm/upex-algorithm-getall-skill-sdk.git",
+  "license": "Proprietary",
+  "skills": "./skills/getagent/"
+}

package/README.md

@@ -0,0 +1,99 @@
+# GetAgent Skill
+
+> Author, backtest, and ship algorithmic crypto trading strategies on Bitget — through your AI coding agent.
+
+[![npm version](https://img.shields.io/npm/v/@bitget-ai/getagent-skill.svg)](https://www.npmjs.com/package/@bitget-ai/getagent-skill)
+
+GetAgent is Bitget's managed platform for AI-authored quantitative trading
+strategies (Playbooks). This Agent Skill teaches your AI coding agent —
+Claude Code, Cursor, or Codex — the full end-to-end GetAgent workflow:
+writing strategy code in Python, validating it locally, uploading to the
+managed sandbox, running historical backtests, publishing accepted
+versions, and opening subscriptions.
+
+## Quick Start
+
+```bash
+npx @bitget-ai/getagent-skill install --client claude
+```
+
+Then open Claude Code and ask:
+
+> Build me a momentum strategy on BTC perp using EMA crossover and run a 30-day backtest.
+
+The agent scaffolds a Playbook package, writes the strategy code, validates
+it locally, uploads it to GetAgent Cloud, runs the backtest in the managed
+sandbox, and shows you results — all without leaving the chat.
+
+For other agents:
+
+```bash
+npx @bitget-ai/getagent-skill install --client cursor   # installs to ~/.cursor/skills/getagent
+npx @bitget-ai/getagent-skill install --client codex    # installs to ~/.codex/skills/getagent
+npx @bitget-ai/getagent-skill install --client all      # all three
+```
+
+## How It Works
+
+GetAgent splits authoring from execution:
+
+- **Local (your machine, via this skill)** — write strategy Python, validate
+  package structure, call the Playbook control-plane API through your agent.
+- **Managed sandbox (GetAgent Cloud)** — the real `getagent.data`,
+  `getagent.trade`, `getagent.llm`, and `getagent.backtest` modules execute
+  with live market data and brokered exchange access.
+
+You write code against the documented `getagent.*` API. When your agent
+uploads the Playbook, GetAgent provisions a matching sandbox image and runs
+the code there, not on your laptop. API keys, market data licensing, and
+execution risk all stay inside the managed boundary.
+
+A typical Playbook entry point looks like:
+
+```python
+from getagent import backtest, data, runtime
+
+def run() -> None:
+    bars = data.crypto.futures.kline(symbol="BTCUSDT", interval="1h", limit=1000)
+    frame = backtest.prepare_frame(bars)
+    # ... your strategy emits signals via runtime ...
+    runtime.emit_signal(action="buy", symbol="BTCUSDT", confidence=0.8)
+```
+
+A complete reference strategy lives in
+[`skills/getagent/examples/btc-ema-cross-demo/`](skills/getagent/examples/btc-ema-cross-demo/).
+
+## What's In The Skill
+
+- **`SKILL.md`** — agent instructions, conversation templates, control flow
+- **`references/`** — package schema, API reference, sandbox runtime, and authoring docs
+- **`scripts/validate.py`** — static package validator (runs locally before upload)
+- **`examples/`** — runnable example Playbooks
+
+## Requirements
+
+- **Node.js 18+** to install the skill via npm
+- **Python 3.11+** for local static validation
+- A **GetAgent Cloud** account and API credentials — your agent will guide
+  authentication on first use
+
+## Versioning
+
+This package follows [Semantic Versioning](https://semver.org/):
+
+- **Patch** (`v0.1.x`) — bug fixes, doc updates, reference regen with no API change
+- **Minor** (`v0.x.0`) — additive: new endpoints, new examples, new authoring surfaces
+- **Major** (`vX.0.0`) — breaking changes to the documented authoring API
+
+If the skill documents an API, the sandbox image GetAgent Cloud provisions
+for your Playbook contains that API.
+
+## License
+
+Proprietary. See [`package.json`](package.json).
+
+## Support
+
+- Issues: https://github.com/Bitget-AI/getagent-skill/issues
+- Skill content: open `~/.claude/skills/getagent/SKILL.md` (or the matching
+  path for cursor/codex) after install

package/VERSION

@@ -0,0 +1 @@
+0.2.1

package/bin/getagent-skill.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const CLIENT_TARGETS = {
+  claude: path.join(os.homedir(), ".claude", "skills", "getagent"),
+  cursor: path.join(os.homedir(), ".cursor", "skills", "getagent"),
+  codex: path.join(os.homedir(), ".codex", "skills", "getagent"),
+};
+
+function usage() {
+  return `GetAgent Skill installer
+
+Usage:
+  npx @bitget-ai/getagent-skill install [--client claude|cursor|codex|all] [--target PATH] [--dry-run]
+  npx @bitget-ai/getagent-skill --help
+
+Examples:
+  npx @bitget-ai/getagent-skill install --client claude
+  npx @bitget-ai/getagent-skill install --client cursor
+  npx @bitget-ai/getagent-skill install --client all
+`;
+}
+
+function parseArgs(argv) {
+  const options = {
+    command: "",
+    client: "all",
+    target: "",
+    dryRun: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--help" || arg === "-h") {
+      options.command = "help";
+      continue;
+    }
+    if (!options.command && !arg.startsWith("-")) {
+      options.command = arg;
+      continue;
+    }
+    if (arg === "--client" || arg === "-c") {
+      options.client = argv[index + 1] || "";
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--client=")) {
+      options.client = arg.slice("--client=".length);
+      continue;
+    }
+    if (arg === "--target" || arg === "-t") {
+      options.target = argv[index + 1] || "";
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--target=")) {
+      options.target = arg.slice("--target=".length);
+      continue;
+    }
+    if (arg === "--dry-run") {
+      options.dryRun = true;
+      continue;
+    }
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  return options;
+}
+
+function expandHome(value) {
+  if (!value) {
+    return value;
+  }
+  if (value === "~") {
+    return os.homedir();
+  }
+  if (value.startsWith("~/")) {
+    return path.join(os.homedir(), value.slice(2));
+  }
+  return value;
+}
+
+function copySkill(sourceDir, targetDir, dryRun) {
+  const resolvedTarget = path.resolve(expandHome(targetDir));
+  if (dryRun) {
+    console.log(`[dry-run] install ${sourceDir} -> ${resolvedTarget}`);
+    return;
+  }
+
+  fs.mkdirSync(path.dirname(resolvedTarget), { recursive: true });
+  fs.rmSync(resolvedTarget, { recursive: true, force: true });
+  fs.cpSync(sourceDir, resolvedTarget, { recursive: true });
+  console.log(`Installed GetAgent skill at ${resolvedTarget}`);
+}
+
+function run() {
+  const options = parseArgs(process.argv.slice(2));
+  if (!options.command || options.command === "help") {
+    console.log(usage());
+    return;
+  }
+  if (options.command !== "install") {
+    throw new Error(`Unknown command: ${options.command}`);
+  }
+
+  const sourceDir = path.resolve(__dirname, "..", "skills", "getagent");
+  if (!fs.existsSync(path.join(sourceDir, "SKILL.md"))) {
+    throw new Error(`Bundled GetAgent skill is missing: ${sourceDir}`);
+  }
+
+  const client = String(options.client || "").toLowerCase();
+  if (options.target) {
+    copySkill(sourceDir, options.target, options.dryRun);
+    return;
+  }
+
+  if (client === "all") {
+    for (const target of Object.values(CLIENT_TARGETS)) {
+      copySkill(sourceDir, target, options.dryRun);
+    }
+    return;
+  }
+
+  const target = CLIENT_TARGETS[client];
+  if (!target) {
+    throw new Error(`Unsupported client: ${options.client}. Use claude, cursor, codex, or all.`);
+  }
+  copySkill(sourceDir, target, options.dryRun);
+}
+
+try {
+  run();
+} catch (error) {
+  console.error(`getagent-skill: ${error.message}`);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@bitget-ai/getagent-skill",
+  "version": "0.2.1",
+  "description": "Install the official GetAgent Agent Skill for Playbook authoring.",
+  "license": "Proprietary",
+  "homepage": "https://github.com/Bitget-AI/getagent-skill#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Bitget-AI/getagent-skill.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Bitget-AI/getagent-skill/issues"
+  },
+  "type": "commonjs",
+  "bin": {
+    "getagent-skill": "bin/getagent-skill.js"
+  },
+  "files": [
+    "bin/",
+    "skills/getagent/",
+    "README.md",
+    "VERSION",
+    ".claude-plugin/"
+  ],
+  "scripts": {
+    "check": "node bin/getagent-skill.js --help && python3 -m py_compile skills/getagent/scripts/validate.py && python3 skills/getagent/scripts/validate.py skills/getagent/examples/btc-ema-cross-demo",
+    "test": "npm run check"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "getagent",
+    "agent-skills",
+    "claude-code",
+    "cursor",
+    "codex",
+    "trading",
+    "playbook",
+    "backtesting"
+  ]
+}

package/skills/getagent/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: getagent
+description: >-
+  Authors, validates, uploads, backtests, publishes, and enables GetAgent
+  quantitative trading Playbooks. Use when the user asks to create, review,
+  fix, validate, upload, run, publish, or subscribe to a trading strategy or
+  Playbook; mentions strategy backtesting, 策略, 回测, 发布, 上传, BTC EMA, or
+  GetAgent; or provides existing Playbook package code for review.
+compatibility: >-
+  Designed for Claude Code, Codex, Cursor, and other agents that support
+  Agent Skills. Requires Python 3.11+ for local static validation and network
+  access to the GetAgent Playbook control-plane API for upload/run/publish.
+metadata:
+  author: getagent
+  version: v0.2.1
+---
+
+# GetAgent Playbook Creator
+
+This skill helps an agent turn a strategy idea into a GetAgent Playbook package,
+validate it locally, upload it to GetAgent Cloud, run sandbox backtests or
+evaluations, publish accepted versions, and enable subscriptions.
+
+Local authoring is **not** local SDK execution. User machines can only run
+static package checks and call the Playbook control-plane APIs. `getagent.data`,
+`getagent.trade`, `getagent.llm`, `getagent.backtest`, and `getagent.runtime`
+are sandbox-preinstalled SDK modules. Use the bundled references to write code
+against their public shape, but do not try to execute data, trade, or LLM SDK
+calls on the user's machine.
+
+## First Use
+
+On first use each session:
+
+1. If available, run `scripts/version_check.sh`. Show update instructions only
+   when it prints a message.
+2. Read `references/package-schema.md` before creating or modifying a package.
+3. Read `references/sdk.md` before writing `src/**` strategy code.
+4. Read the exact API reference under `references/api/` before upload, run,
+   publish, enable, or list operations.
+
+## User Opening
+
+When the user asks generally how to start, use this stable opening in the
+user's language. Do not ask for credentials in the opening.
+
+```text
+✅ 策略回测助手已经准备好了。
+
+我可以帮你完成从「策略想法」到「沙箱回测结果」的完整流程：
+
+- 你可以用自然语言描述策略，我会生成可运行代码
+- 你也可以提供已有策略，我会帮你 review、修复和优化
+- 我会先做本地校验，检查策略是否符合回测框架要求
+- 校验通过后，我可以上传到沙箱并启动回测
+- 回测完成后，我会帮你解读收益、回撤、胜率、交易次数等结果
+- 然后我们可以继续迭代下一版策略
+
+你现在想怎么开始？
+
+A. 跑一个 Demo，先看看完整流程（BTC EMA 趋势策略，仅信号模式）
+B. 我有大致方向，让你帮我搭个最小骨架（你会反问我几个关键问题：标的 / 周期 / 进场 / 出场）
+C. 我直接描述我的策略想法
+D. 我已有策略代码（贴在这里或给路径），先 review 修复再跑回测
+```
+
+Use the English equivalent when the user's first message is English.
+
+## Default Workflow
+
+1. Clarify only missing strategy requirements that block authoring. Ask one
+   concrete question at a time.
+2. Scaffold the package shape from `references/package-schema.md`.
+3. Write strategy code against `getagent.*` imports only, plus allowed
+   scientific/runtime packages documented in the schema.
+4. Validate locally:
+
+   ```bash
+   conda activate get_agent_test
+   python "scripts/validate.py" ./my-strategy/
+   ```
+
+5. Ask for the user's Bitget OpenAPI `ACCESS-KEY` only before the first
+   authenticated upload/run/publish/enable call. Never write credentials to disk.
+6. Upload the package through the documented control-plane API.
+7. Run a sandbox evaluation before publish when the package supports backtests.
+8. Read results back in plain language before proposing publish or iteration.
+
+## Reference Map
+
+- Package contract: `references/package-schema.md`
+- SDK overview: `references/sdk.md`
+- Sandbox runtime and blocked imports: `references/sandbox-runtime.md`
+- Backtest engine behavior: `references/backtest-engine.md`
+- Control-plane APIs: `references/api/index.md`
+- Data SDK: `references/sdk/data/playbook-supported.md`
+- Trade SDK: `references/sdk/trade/patterns.md`
+- Backtest SDK: `references/sdk/backtest/catalog.md`
+- Runtime SDK: `references/sdk/runtime/catalog.md`
+- LLM SDK: `references/sdk/llm/catalog.md`
+
+## Hard Boundaries
+
+- Do not tell users to install or execute the private GetAgent SDK locally.
+- Do not import or recommend direct clients such as `requests`, `httpx`,
+  `ccxt`, `trade_sdk`, `yfinance`, `akshare`, or exchange clients in Playbook
+  source code.
+- Do not use `getagent.llm` for replayable historical logic. LLM-backed
+  strategies are live/evaluation-only and require `runtime_profile:
+  llm_bounded` with `backtest_support: none`.
+- Do not call trade mutation APIs directly in a signal-only branch. Emit the
+  signal successfully and let the runtime decide whether follow-trade is
+  allowed.
+- Do not publish or enable without showing the endpoint and masked
+  `ACCESS-KEY` prefix and getting the user's intent for that operation.
+
+## Post-Backtest Response
+
+After every successful sandbox run, summarize the result before any next action:
+
+- strategy-basis `total_return_pct`
+- `max_drawdown_pct`
+- `win_rate` paired with `total_trades`
+- finite `sharpe_ratio` only when trades exist
+- the main risk revealed by the run
+
+Then offer 2-3 concrete next moves: tune a declared parameter, change symbol or
+timeframe within schema, revise entry/exit logic in a new version, or publish
+only if evidence is acceptable.

package/skills/getagent/examples/btc-ema-cross-demo/README.md

@@ -0,0 +1,61 @@
+# BTC EMA Crossover Demo
+
+A minimal trend-following Playbook on BTC perpetual futures, used as an
+end-to-end walkthrough of the GetAgent Playbook Creator skill.
+
+## 策略
+
+This Playbook captures sustained directional moves on BTC perpetual futures.
+It runs on 1-hour bars and bets on the assumption that, once a trend forms,
+price tends to travel along that trend in a relatively clean direction
+rather than chopping back and forth.
+
+The decision is driven by alignment between two moving averages of different
+horizons. When the shorter horizon clearly leads the longer horizon upward,
+the strategy reads it as bullish alignment. When it falls below the longer
+horizon, the strategy reads it as bearish alignment.
+
+## 开仓
+
+The Playbook opens a long position when the short-horizon trend crosses
+above the long-horizon trend, indicating that recent momentum has flipped
+in favor of the upside. It opens a short position on the inverse cross.
+
+There is no fading of extremes, no top-picking, and no pyramiding. Only the
+crossover event is treated as actionable.
+
+## 平仓
+
+A position is closed on the inverse crossover. When the short-horizon
+trend retracts below the long-horizon trend (for longs) or back above it
+(for shorts), the strategy interprets that as a fade of conviction and
+exits the position. Stop loss and take profit are not used in this demo —
+the cross alone exits the trade.
+
+## 参数说明
+
+Subscribers may tune two parameters at subscription time:
+
+- **leverage** — amplifies both upside and drawdown equally. Higher leverage
+  does not make the strategy more selective; it only sizes risk larger.
+- **margin_budget** — per-strategy capital cap, used by the platform to size
+  orders and to compute the user-facing return percentage.
+
+## 回测指标如何读
+
+The backtest reports `total_return_pct`, `sharpe_ratio`, `max_drawdown_pct`,
+`win_rate`, and `total_trades`. `total_return_pct` is the strategy-budget
+return (`net_pnl / margin_budget`); `account_total_return_pct` is the raw
+account-level number from the engine. Pay attention to drawdown depth and
+total trade count alongside return — a high return on too few trades is not
+robust evidence.
+
+## 风险
+
+This demo strategy underperforms in choppy, range-bound markets where the
+short-horizon trend flips repeatedly without committing to a real trend.
+Around major news gaps and persistent funding-rate dislocation it can
+produce a string of stops or trapped positions. Past historical performance
+is not a guarantee of live profitability — match it against your own risk
+tolerance before subscribing, and do not run it with leverage you cannot
+afford to draw down.

package/skills/getagent/examples/btc-ema-cross-demo/backtest.yaml

@@ -0,0 +1,33 @@
+venue:
+  name: BINANCE
+  account_type: MARGIN
+  oms_type: NETTING
+  starting_balances:
+    - amount: 100000
+      currency: USDT
+
+strategy:
+  module: strategy
+  class: EmaCrossStrategy
+  config_class: EmaCrossStrategyConfig
+  config:
+    order_id_tag: "001"
+    trade_size: "0.01"
+    fast_period: 12
+    slow_period: 26
+
+instrument:
+  id: BTCUSDT.BINANCE
+  kind: perpetual
+  raw_symbol: BTCUSDT
+  base_currency: BTC
+  quote_currency: USDT
+  settlement_currency: USDT
+  price_precision: 2
+  size_precision: 3
+  price_increment: "0.01"
+  size_increment: "0.001"
+  lot_size: "0.001"
+  maker_fee: "0.0002"
+  taker_fee: "0.0005"
+  bar_type: BTCUSDT.BINANCE-1-HOUR-LAST-EXTERNAL

package/skills/getagent/examples/btc-ema-cross-demo/manifest.yaml

@@ -0,0 +1,94 @@
+name: btc-ema-cross-demo
+display_name: "BTC EMA Crossover Demo"
+version: "1.0.1"
+description: "Trend-following BTC perpetual demo using EMA crossover on hourly bars"
+long_description: |
+  This Playbook is a trend-following strategy on BTC perpetual futures that
+  aims to capture the middle portion of sustained directional moves. The
+  thesis is simple: once the broader market commits to a real trend, price
+  tends to travel along that direction in a relatively clean way rather
+  than chopping back and forth. The Playbook deliberately ignores fade
+  setups and range-bound conditions and only acts when a crossover event
+  signals that a fresh directional regime has formed. It is designed for
+  subscribers who want a transparent, easy-to-explain signal source rather
+  than a black-box model.
+
+  Entry decisions are driven by alignment between a shorter-horizon and a
+  longer-horizon directional read of price action. When the shorter
+  horizon clearly leads the longer horizon upward, the strategy treats
+  that as bullish alignment and enters long. When the shorter horizon
+  drops below the longer horizon, it treats that as bearish alignment and
+  enters short. The strategy waits for the crossover to happen rather
+  than anticipating it, accepting some delay in exchange for clearer
+  confirmation.
+
+  Exits work by inversion. When the shorter horizon retracts back through
+  the longer horizon, the strategy reads that as fading conviction and
+  closes the position to lock in whatever was captured. The Playbook does
+  not use a separate stop loss or take profit in this demo; the crossover
+  itself is both the exit gate and the regret-control mechanism. Many
+  small losing trades are treated as the cost of catching the occasional
+  larger trend run.
+
+  Subscribers may tune two parameters. Leverage amplifies both upside and
+  drawdown equally; raising leverage does not make the strategy more
+  selective, it only sizes risk larger. Margin budget is the per-strategy
+  capital cap that the platform sizes orders against and uses as the
+  denominator for return percentage; treat it as the maximum amount you
+  are willing to put at risk on this Playbook.
+
+  The strategy underperforms in choppy, range-bound markets where the
+  shorter horizon flips repeatedly without committing to a real trend,
+  producing whipsaw losses. Gap-driven moves around major news events and
+  persistent funding-rate dislocation can also create a string of trapped
+  positions. Past historical backtest performance is not a guarantee of
+  live profitability, and live execution will pay slippage and exchange
+  fees that erode edge — only subscribe if you can tolerate the drawdown
+  and unsuitable regime risk this kind of trend strategy carries.
+
+market_type: contract
+trading_symbols: ["BTCUSDT"]
+tags: ["trend", "ema", "btc", "contract", "demo"]
+
+decision_mode: deterministic
+backtest_support: full
+runtime_profile: deterministic
+execution_mode: signal_only
+follow_trade_supported: false
+
+strategy_config:
+  trading_symbols: ["BTCUSDT"]
+  fast_period: 12
+  slow_period: 26
+  leverage: 3
+  margin_budget: "100"
+
+user_config_schema:
+  trading_symbols:
+    type: array
+    item_type: string
+    default: ["BTCUSDT"]
+    options: ["BTCUSDT", "ETHUSDT", "SOLUSDT"]
+    aliases:
+      btc: BTCUSDT
+      bitcoin: BTCUSDT
+      eth: ETHUSDT
+    min_items: 1
+    max_items: 1
+    label: "Trading symbol"
+  leverage:
+    type: integer
+    default: 3
+    min: 1
+    max: 10
+    aliases:
+      3x: 3
+      3倍: 3
+      5x: 5
+      5倍: 5
+    label: "Leverage"
+  margin_budget:
+    type: string
+    default: "100"
+    pattern: "^[0-9]+(\\.[0-9]+)?$"
+    label: "Margin budget USDT"