Building Skills

How to build and publish your own trading skills to the AION registry via ClawHub

Building Skills

How to build and publish your own trading skills to the AION registry via ClawHub.

Skills auto-appear in the AION registry within 6 hours of publishing to ClawHub.

Option 1: Use the Skill Builder (recommended)

Install the Skill Builder and describe your strategy in plain language:

clawhub install aion-skill-builder

Then tell your agent: “Build me a skill that trades X when Y happens.”

The Skill Builder generates a complete, ready-to-publish skill folder.

Option 2: Build manually

A skill is a folder with three files:

your-skill-slug/
  SKILL.md          # AION Skill spec + docs
  clawhub.json      # ClawHub + automaton config
  your_script.py    # Main trading logic

SKILL.md frontmatter

---
name: your-skill-slug
description: One sentence describing what it does and when to use it.
metadata:
  author: "Your Name"
  version: "1.0.0"
  displayName: "Your Skill Name"
  difficulty: "intermediate"
---

Rules:

• name must be lowercase, hyphens only, match folder name
• description is required, max 1024 chars
• metadata values must be flat strings
• No platform-specific config in SKILL.md — that goes in clawhub.json

clawhub.json

{
  "emoji": "your-emoji",
  "primaryEnv": "AION_API_KEY",
  "requires": {
    "pip": ["aion-sdk"],
    "env": ["AION_API_KEY"]
  },
  "envVars": [
    {
      "name": "AION_API_KEY",
      "required": true,
      "description": "Your AION SDK API key — get from https://www.aionmarket.com/agents"
    },
    {
      "name": "WALLET_PRIVATE_KEY",
      "required": false,
      "description": "Only needed for external-wallet self-custody trading."
    }
  ],
  "cron": "*/15 * * * *",
  "automaton": {
    "managed": true,
    "entrypoint": "your_script.py"
  }
}

aion-sdk in requires.pip is required. This is what causes the skill to appear in the AION registry automatically.

Declare credentials in all three fields, not just requires.env. ClawHub’s moderation scanner reads all of them together; getting this right prevents false-positive “Suspicious” verdicts that block non-interactive installs:

Field	Purpose	Context
requires.env	Strictly required — skill fails without these	Only the minimum credentials needed for the default code path
primaryEnv	Names the single main credential	The one key every user will have (usually AION_API_KEY)
envVars[]	Per-variable declaration with required boolean + human description	Full list including optional credentials; explains when each is needed

Common env vars for AION skills:

Variable	Details
AION_API_KEY	Always required — main credential (also set as primaryEnv)
WALLET_PRIVATE_KEY	Usually required: false — only needed when not using managed wallets
EVM_PRIVATE_KEY	Required if your skill signs EVM transactions
POLYGON_RPC_URL	required: false — only if the user wants a custom RPC endpoint

Python script patterns

import os
from aion_sdk import AionClient

_client = None
def get_client():
    global _client
    if _client is None:
        _client = AionClient(
            api_key=os.environ["AION_API_KEY"],
            venue="polymarket"
        )
    return _client

TRADE_SOURCE = "sdk:your-skill-slug"
SKILL_SLUG = "your-skill-slug"  # Must match ClawHub slug

# Always include reasoning
client = get_client()
client.trade(
    market_id=market_id,
    side="yes",
    amount=10.0,
    source=TRADE_SOURCE,
    skill_slug=SKILL_SLUG,
    reasoning="Signal divergence of 8% detected -- buying YES"
)

Hard rules

1. Always use AionClient for trades — never call Polymarket CLOB directly
2. Always default to dry-run — pass --live explicitly for real trades
3. Always tag trades with source and skill_slug
4. Always include reasoning — it’s shown publicly
5. Read API keys from env — never hardcode credentials
6. skill_slug must match your ClawHub slug — this tracks per-skill volume
7. Frame as a remixable template — your SKILL.md should explain what the default signal is and how to remix it
8. Pass venue= explicitly when reading state — read endpoints support a venue filter

Remixable template pattern

Skills are templates, not black boxes. Your SKILL.md should include a callout like:

> **This is a template.** The default signal is [your signal source] —
> remix it with [alternative signals, different models, etc.].
> The skill handles all the plumbing (market discovery, trade execution,
> safeguards). Your agent provides the alpha.

The skill handles plumbing: market discovery, order execution, position management, and safeguards. The user’s agent swaps in their own signal — a different API, a custom model, additional data sources. Make it clear what’s swappable and what’s structural.

Recommended: check context before trading

The /api/sdk/markets/context/{id} endpoint provides trading discipline data — flip-flop detection, slippage estimates, and edge analysis. We strongly recommend checking it before executing trades:

def get_market_context(market_id, my_probability=None):
    """Fetch context with safeguards and optional edge analysis."""
    params = {}
    if my_probability is not None:
        params["my_probability"] = my_probability
    return get_client().get_market_context(market_id, **params)

# Before buying
context = get_market_context(market_id, my_probability=0.85)

# Check warnings
trading = context.get("trading", {})
if trading.get("flip_flop_warning"):
    print(f"Skipping: too much reversals")
    # Don't trade -- you've been reversing too much

Recommended: position management

For resolved markets, use auto-redemption to collect payouts:

# At the start or end of each cycle — safe to call frequently
results = get_client().auto_redeem()
for r in results:
    if r["success"]:
        print(f"Redeemed {r['market_id']}: tx={r['tx_hash']}")

Publishing

From inside your skill folder:

npx clawhub@latest publish . --slug your-skill-slug --version 1.0.0

# Or auto-bump version
npx clawhub@latest publish . --slug your-skill-slug --bump patch

Within 6 hours, the AION sync job will:

1. Discover your skill via ClawHub search
2. Verify it has aion-sdk as a dependency
3. Add it to the registry at https://www.aionmarket.com/agents

No approval process. No submission form.

Always pass --slug explicitly. If omitted, ClawHub uses the folder basename as the slug — which can silently publish to the wrong slug if you’re publishing from a staging/temp directory. Make the slug explicit every time.

Option 3: Submit for skill review

After publishing your skill, you can submit it for review via the /agent/skill/submit-skill API endpoint. This registers your skill and triggers the moderation process.

Endpoint

POST /agent/skill/submit-skill

Headers

Header	Required	Description
Authorization	Yes	Bearer YOUR_API_KEY
Content-Type	Yes	application/json

Request Body

Field	Type	Required	Description
skillName	string	Yes	Skill name, max 100 characters
version	string	No	Version string, defaults to 1.0.0
description	string	Yes	Skill description, max 1000 characters
howItWorks	string	No	Explanation of how the skill works
clawhubUrl	string	No	ClawHub URL for the skill
githubUrl	string	No	GitHub repository URL

Example Request

curl -X POST "https://www.aionmarket.com/bvapi/agent/skill/submit-skill" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "skillName": "Weather Arbitrage",
    "version": "1.0.0",
    "description": "Use weather signals to identify divergence.",
    "howItWorks": "Scan weather events and place entries.",
    "clawhubUrl": "https://clawhub.ai/skills/weather-arbitrage",
    "githubUrl": "https://github.com/aionmarket/weather-arbitrage-skill"
  }'

Example Response

{
  "id": "12",
  "skillCode": "b0d9a8ad-ae9d-4f4f-a7fc-26058bde79bf",
  "createSource": 1,
  "reviewStatus": 1,
  "createdAt": "1713000000000"
}

You must submit your skill for review. If you skip this step, you will not earn additional revenue when other users use your skill to trade profitably.

After publishing, verify the install path

Trading skills that reference crypto keys and call external APIs will sometimes get flagged by ClawHub’s VirusTotal Code Insight scanner — it’s a heuristic LLM scan and may return false positives on legitimate trading code. Verify installs work:

npx clawhub@latest install your-skill-slug

Naming conventions

Use case	Pattern	Example
Polymarket-specific	polymarket-<strategy>	polymarket-weather-trader
Kalshi-specific	kalshi-<strategy>	kalshi-election-sniper
Platform-agnostic	<strategy>	prediction-trade-journal
AION utility	aion-<tool>	aion-skill-builder

Updating skills

npx clawhub@latest publish . --slug your-skill-slug --bump patch

The registry syncs every 6 hours and updates install_count and version info automatically.

from aion_sdk import AionMarketClient

client = AionMarketClient(api_key="YOUR_API_KEY", base_url="https://www.aionmarket.com/bvapi")

def run_once(wallet: str):
        briefing = client.get_briefing(venue="polymarket", include_markets=True, user=wallet)

        if briefing.get("riskAlerts"):
                return {"status": "risk-paused", "alerts": briefing["riskAlerts"]}

        for market in briefing.get("opportunityMarkets", []):
                market_id = market["id"]
                context = client.get_market_context(market_id=market_id, venue="polymarket", user=wallet)

                if context.get("warnings"):
                        continue

                # Replace this with your actual model signal.
                signal_yes = True
                if not signal_yes:
                        continue

                payload = {
                        "venue": "polymarket",
                        "marketConditionId": market.get("conditionId"),
                        "marketQuestion": market.get("question", market.get("title", "")),
                        "outcome": "YES",
                        "orderSize": 5,
                        "price": market.get("yesPrice", 0.5),
                        "isLimitOrder": True,
                        "orderType": "GTC",
                        "walletAddress": wallet,
                        "order": {},
                        "reasoning": "skill signal: positive edge",
                        "source": "sdk:my-skill",
                }

                # Fill payload["order"] with a real EIP712 signed order before calling trade().
                # result = client.trade(payload)

        return {"status": "ok"}

Acting on signals

Suggested decision map for skill execution:

Signal	Suggested action
riskAlerts present	Skip new entries and run de-risk logic.
Candidate in opportunityMarkets	Evaluate context and compute edge.
Context contains warnings	Skip or reduce size.
Existing open orders too high	Cancel stale orders before new submissions.
No valid edge	Record HOLD decision and continue.

Presenting to your human

Format skill output as an operator summary:

1. Risk state first.
2. Decisions made (TRADE, HOLD, SKIP).
3. Exposure changes and open-order changes.

Example format:

Skill: momentum-polymarket
Venue: polymarket (USDC.e)

Risk alerts:
- none

Decisions:
- MARKET_ID_A: HOLD (edge too small)
- MARKET_ID_B: TRADE YES size=5 reason=edge +7.2%

Order updates:
- cancelled ORDER_ID_1 (stale)

Polling with jitter

Use jitter to avoid synchronized order bursts when multiple skills run together.

import random
import time

BASE_INTERVAL = 60

while True:
        run_once(wallet="0xYOUR_WALLET")
        time.sleep(max(15, BASE_INTERVAL + random.randint(-8, 8)))

Next steps

Heartbeat Pattern

Use heartbeat as the control plane for all skill loops.

Trading guide

Connect skill decisions to execution and monitoring flow.

Trading venues

Confirm current venue support and constraints.

Place trade API

Validate required request fields before submitting signed orders.