aggclaw

SKILL.md

---
name: aggclaw
description: "AppGrowing Global intelligent ad creative analysis assistant. Connects to the Explore mode API to analyze user intent, find the most relevant overseas ad creatives, and deliver automated analysis. Triggers: keywords analyze creatives, creative analysis, overseas campaigns, explore creatives, find creatives; commands /aggclaw, /aggclaw-game, /aggclaw-app, /aggclaw-shortdrama"
homepage: https://appgrowing.net/
metadata:
  {
    "openclaw": {
      "slug": "aggclaw",
      "version": "1.0.0",
      "author": "youcloud",
      "emoji": "🌍",
      "requires": {
        "env": ["YOUCLOUD_API_KEY"]
      }
    }
  }
---

# aggclaw

AppGrowing Global intelligent ad creative analysis assistant. Connects to the Explore mode API to analyze user intent, find the most relevant overseas ad creatives, and deliver automated analysis — allowing users to interact directly with creative insights.

## Access

Available to **AIplus** and **Premium** subscribers of AppGrowing Global. To get an API Key: log in to AppGrowing Global → Profile → Enterprise Info.

## Triggers

- Keywords: analyze creatives, creative analysis, overseas campaigns, explore creatives, find creatives
- Commands:
  - `/aggclaw` → Auto-detect game/non-game mode
  - `/aggclaw-game` → Game mode (`chat_mode=7`)
  - `/aggclaw-app` → Non-game app mode (`chat_mode=8`)
  - `/aggclaw-shortdrama` → Short drama mode (`chat_mode=8`)

## Language Detection

Before any API call, detect the language of the user's input and respond in that language throughout the session.

- **Detection rule:** If the user's input contains Chinese characters (CJK Unified Ideographs), respond in Chinese. Otherwise, respond in English.
- This language preference persists for the entire session (including follow-up questions within the same session_id).
- The `input` field sent to the API should remain in the user's original language — do not translate the user's query.
- All framing text, error messages, and summaries added by the agent should be in the detected language.

## Execution Flow

1. **Check API Key** (read from environment variable `YOUCLOUD_API_KEY`):
   - Key present → proceed
   - Key empty/missing → prompt user to configure:
     ```
     Please configure your API Key first:
     1. Log in to AppGrowing Global → Profile → Enterprise Info to get your API Key
     2. Set it as environment variable YOUCLOUD_API_KEY, e.g.:
        - Linux/macOS: export YOUCLOUD_API_KEY="your-key-here"
        - Windows: $env:YOUCLOUD_API_KEY="your-key-here"
     3. Send your request again after configuration.
     ```
   - ✅ Rule: **Never send requests without a valid API Key**

2. **⚠️ Mandatory Timeout Rules**
   - API request timeout: **600 seconds**
   - **🔴 Absolutely forbidden: do NOT interrupt a request before timeout, do NOT send any "still processing" or "will let you know" messages**
   - **Must: wait for the API to return a complete result, then reply to the user in one shot**
   - Only two situations allow sending a message:
     1. API returns a complete analysis result → output the result directly
     2. API timeout or request error → output error message

3. **Detect Language** (see Language Detection section above)

4. **Determine chat_mode:**
   - **Command-specified:**
     - `/aggclaw-game` → Game mode (`chat_mode=7`)
     - `/aggclaw-app`, `/aggclaw-shortdrama` → Non-game mode (`chat_mode=8`)
   - **Auto-detect (keyword/content trigger):**
     - Input contains game-related content (game titles, gaming terminology like RPG/SLG/MMO) → Game mode (`chat_mode=7`)
     - Other content (apps, e-commerce, utilities, short dramas) → Default non-game mode (`chat_mode=8`)

5. **Call the API directly — do NOT ask the user questions:**
   - When the user initiates a creative analysis request, assemble the intent into an `input` and call the API directly. Do not ask for product positioning, target market, or other supplementary info — let the API search and analyze on its own.
   - New analysis request → start a new session, pass `chat_mode`, do NOT carry `session_id`
   - Follow-up question (about a previous analysis) → reuse the previous `session_id`, do NOT pass `chat_mode` (keep the session's existing mode)
   - Output the API response result directly.

## API Specification

- URL: `https://ai-chat-global.youcloud.com/aichat/claw`
- Method: POST JSON
- Headers: `Authorization: Bearer {KEY}`, `Content-Type: application/json`
- Parameters:
  - `input`: User question (required)
  - `session_id`: For follow-up questions, omit for new conversations
  - `chat_mode`: Chat mode, 7=game, 8=non-game. **Only pass for new conversations (no session_id); omit for follow-ups to preserve the session's mode**
- Response: Output `output` (markdown) **as-is unless the user's language differs from the API response language — in that case, translate the output to the user's language**; save `session_id` for future follow-ups
- Timeout: ≥600s

## PowerShell Call Template

```powershell
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$apiKey = $env:YOUCLOUD_API_KEY
$body = @{input="Your analysis request"; chat_mode=8} | ConvertTo-Json -Compress
$params = @{
  Uri = "https://ai-chat-global.youcloud.com/aichat/claw"
  Method = "Post"
  ContentType = "application/json; charset=utf-8"
  Headers = @{Authorization="Bearer $apiKey"}
  Body = $body
  TimeoutSec = 600
}
Invoke-RestMethod @params | Select-Object -ExpandProperty output
```

## Error Handling

- 400 Invalid credentials / 401 Authentication failed:
  ```
  API Key authentication failed. Please check if your key is active or expired. Get your API Key from AppGrowing Global Profile → Enterprise Info, or contact support.
  ```
- 400 "System error" (API returns "Sorry, system error, please try again later."):
  - Repeated occurrences indicate temporary server instability, unrelated to API Key or request content.
  - Retry strategy: try a more generic/shorter query 1-2 times; if still failing, inform the user that the server is temporarily unavailable and suggest trying later.
  - Observed behavior: certain vertical categories (e.g., AI tool apps) may trigger this error due to insufficient creative data; trying an adjacent category (e.g., e-commerce) may work normally.
- Timeout: "Analysis is still in progress. Try asking again or resend your request."
- Other errors: "Request returned an error (code={code}). Please check your API Key permissions, account quota, or contact customer support."

## Notes

- ⚠️ API response time is typically **60 seconds+**, always use a 600-second timeout
- ⚠️ API Key is read from environment variable `YOUCLOUD_API_KEY`

## Examples

For full input/output examples, see [references/example.md](references/example.md)