/academy-skill

name: academy-skill
description: >
  Retrieve Binance Academy's official educational content (Glossary, Courses,
  Learn & Earn, Articles) for AI chat. Trigger when the user's message
  expresses one of these INTENTS (NOT keyword matches):
  (1) Knowledge Q&A — "What is Gas Fee?", "Why did I receive less crypto than I sent?", "How does staking work?"
  (2) Risk Education — high-risk trading/investment intent: leverage, borrowing to trade, all-in, scams, "20x long", "borrowing to amplify position"
  (3) Customized Learning Plan — "I want to learn DeFi", "Build me a 5-day Bitcoin plan", "DeFi learning path for beginners"
  (4) Learn & Earn — "Which Academy courses have rewards?", "一文读懂 X", "What is X (TICKER)?", "courses that pay crypto"
  This skill extracts clean query terms from natural language before calling
  the API. It NEVER gives investment advice — educational content only.
metadata:
  author: binance-academy
  version: "2.0.0"
allowed-tools: Bash Read

Binance Academy AI Skill

Intent-driven educational content skill. Retrieve Glossary / Courses / Learn & Earn / Articles from Binance Academy, present as concise paraphrased answers with Academy links. **Never investment advice.**

When to Use

| Intent | Trigger examples | Primary tool | |---|---|---| | **1. Knowledge Q&A** | "What is X?", "Why does X happen?", "How does X work?" | `searchAll` (parallel) | | **2. Risk Education** | leverage / borrowing / all-in / scams / "20x long" / "borrowing to trade" | `searchAll` + risk-warning block | | **3. Learning Plan** | "I want to learn X", "X learning path", "build me a plan for X" | `getLearningPlan` | | **4. Learn & Earn** | "Which courses have rewards?", "一文读懂 X", "What is X (TICKER)?" | `searchLearnEarn` or `searchAll` |

**Do NOT trigger for:** account/login issues, trading execution ("buy 1 BTC now"), price checks ("what's BTC price"), or small talk.

For ambiguous intent cases (e.g., "什么是 X" vs "20x 杠杆是什么" vs "20x 杠杆可以吗"), see `references/intent-routing.md`.

How to Use

1. Detect user language → `lang` code

Default: `zh` for Simplified Chinese, `en` for English. Full 35-code list in `references/languages.md`.

2. Pick intent + call the script

All examples use `prod` (the only supported env). `ACADEMY_SKILL_DIR` = this skill's root directory (resolved by the runtime when the skill loads).

# Intent 1, 2 — Knowledge Q&A / Risk Education (parallel dispatch, recommended)
node "$ACADEMY_SKILL_DIR/scripts/academy-api.mjs" prod searchAll \
  '{"query":"gas fee","lang":"en","limit":3}'

# Intent 3 — Learning Plan (use a clean topic noun, NOT the full sentence)
node "$ACADEMY_SKILL_DIR/scripts/academy-api.mjs" prod getLearningPlan \
  '{"query":"DeFi","lang":"en","limit":3}'

# Intent 4 Pattern A — explicit reward question
node "$ACADEMY_SKILL_DIR/scripts/academy-api.mjs" prod searchLearnEarn \
  '{"query":"reward","lang":"en","limit":5}'

# Intent 4 Pattern B — L&E title format (searchAll catches L&E + verifies)
node "$ACADEMY_SKILL_DIR/scripts/academy-api.mjs" prod searchAll \
  '{"query":"What is Turtle (TURTLE)?","lang":"en","limit":3}'

**`searchAll` response** — use these fields, ignore the rest:

• `best.source` — which endpoint won (`glossary`/`learnEarn`/`resource`/`articles`/`null`)
• `best.items[0]` — the top hit to format (already reordered by match quality)
• `best.matchTier` (0–3) — match-quality band:
• `>= 2` → good match, format the card. Tier 2 is reliable: structured

sources (glossary/learnEarn/resource) whose title is a true superset of the query (adds a concept noun, e.g. `smart contract` → "Smart Contract Wallet") are demoted to tier 1 in code, so a tier-2 hit is either a clean multi-token title match or an articles long-form match.

• `<= 1` → weak match, retry with a clean English keyword (same `lang`)
• `-1` (`best.source == null`) → no hits, use No-Content template
• `glossary` / `learnEarn` / `resource` arrays — used to generate the "Next Step" suggestion; do NOT make extra API calls for it
• `articlesLangFallback` — `true` only when the user explicitly passed a

non-empty `lang` that the articles endpoint does not support (so articles fell back to English); translate the distilled article back to the user's language. `false` when `lang` was omitted/empty (no user language to translate to).

**Query strategy — language-dependent default.**

• **English (and other Latin-script languages)**: *raw input first*.

Send the user's raw input as `query` (the script pre-processes: trim, strip control chars, truncate to 200 chars). Only extract clean keywords when raw input returns `matchTier <= 0` or `best.source == null`. Don't lowercase or translate upfront. Full fallback heuristics in `references/query-extraction.md`.

• **Chinese and other CJK**: *extract keyword first*. CJK raw sentences

almost never hit — a 20-question zh sample showed **0/20 reached tier ≥ 2**. `plainto_tsquery('simple', ...)` does no CJK word segmentation and ANDs every token (including question words like "什么是"), so a CJK sentence rarely matches a short Academy title. **Default to extracting the topic noun + translating to its canonical English term BEFORE the first `searchAll` call** — do NOT first try the raw sentence and then fall back (that wastes a full `searchAll` round-trip on a near-guaranteed `tier <= 1`, and "default strategy never effective for CJK" is exactly the problem this fixes). See `references/query- extraction.md` §4 for the translation table.

• **Exception — bare CJK concept noun with no question words** (钱包,

智能合约, 工作量证明, 区块链): send it raw. Single-token CJK concept nouns DO hit (tier 3) when the Academy has the translated glossary entry, and skipping raw for them would lose the cleanest match. If the raw noun returns `tier <= 1` or off-topic, fall back to the English translation.

• **How to tell a sentence from a bare noun**: if the input contains

ques