byted-marketing-agent-inspiration-insight

Creative Inspiration Insight (InspirationInsight)

When to Use

• /inspiration — manually trigger a full inspiration insight query
• The user asks about "viral creative ideas / shot-by-shot prompts / video inspiration / visual elements / marketing materials"
• The user wants to "replicate a viral hit / analyze a viral video / see key frame screenshots / see ASR text"
• The user wants to learn about a certain industry's "creative direction / content trends / video script references"
• Called by other orchestration skills (such as daily report generation, creative planning)
• Scheduled tasks automatically run to fetch the latest inspiration data

⛔ OUTPUT RULE — highest priority

• During execution,it is forbidden to output any intermediate process to the user, including but not limited to: self-checks, creating virtual environments, installing dependencies, connectivity verification, and other technical steps.
• It is forbidden to output any of the following content (violation means failure):
  • ❌ "Let me first perform a self-check" / "Creating virtual environment" / "Installing dependencies" / "Installation is still in progress"
  • ❌ "Let me first check the skill file" / "First, environment preparation"
  • ❌ API addresses, credentials, tokens, script paths, internal field names, SDK version information
  • ❌ Database table names (such as cdp_voc.hot_video), English field names (such as vv_all、storyboard_prompt), query_type values (such as hot_video) — whether in process or result, it is absolutely forbidden to disclose them to the user
• If the environment is not ready and installation is needed, only one user-friendly prompt is allowed (such as "Initializing the query service for you, please wait..."), and after completion directly return the business result without announcing technical details.
• Only output once after completion: the business result (industry list / insight list / single detail) or "No data available / parameters missing, selection required".

Self-check and environment preparation (must be completed before each execution)

⚠️ Mandatory rules

• All script callsmust use the Python of the virtual environment：$VENV_PY
• On first use or when the self-check fails, you must first complete the "Install virtual environment" step below, then pass the self-check again before executing business calls.
• It is forbidden to directly use the system python3, to avoid dependency pollution or version mismatch.

0. Credential detection (check before environment preparation)

if [ -z "$VOLCENGINE_ACCESS_KEY" ] || [ -z "$VOLCENGINE_SECRET_KEY" ]; then
  echo "CREDENTIALS_MISSING"
else
  echo "VOLCENGINE_ACCESS_KEY: 已设置"
fi

• If the output is CREDENTIALS_MISSING：you must ask the user for credentials, output:

  🔑 Volcengine access credentials need to be configured. Please provide:

  • AccessKey（AK）：
  • SecretKey（SK）：

• After the user provides them, store them in the shell variable VOLC_AK_INPUT / VOLC_SK_INPUT, and append to all subsequent commands --ak "$VOLC_AK_INPUT" --sk "$VOLC_SK_INPUT"。
• If the credentials already exist (VOLCENGINE_ACCESS_KEY / VOLCENGINE_SECRET_KEY is already set), no need to ask, go directly to the self-check.

A. Offline self-check (no network access, run before each execution)

SCRIPTS_DIR=$(dirname "$(find ~ -maxdepth 8 -name "openapi_client.py" -path "*byted-marketing-agent-inspiration-insight*" 2>/dev/null | head -1)")
SKILL_DIR=$(dirname "$SCRIPTS_DIR")
VENV_PY=$SKILL_DIR/venv/bin/python3

# 1) 检查虚拟环境是否存在
test -f $VENV_PY && echo "venv OK" || echo "venv 不存在，请先执行安装步骤"

# 2) 检查依赖是否可用
$VENV_PY -c "import volcenginesdkcore; from volcenginesdkcore import ApiClient; print('deps OK')"

# 3) 检查 volcengine-python-sdk 版本（必须 >= 4.0.43）
$VENV_PY -c "from importlib.metadata import version; print(version('volcengine-python-sdk'))"

# 4) 语法检查
$VENV_PY -m py_compile $SCRIPTS_DIR/openapi_client.py && echo "syntax OK"

Only after the self-check fully passes (no errors) can subsequent business calls be executed.

Install virtual environment (execute when the self-check fails)

SCRIPTS_DIR=$(dirname "$(find ~ -maxdepth 8 -name "openapi_client.py" -path "*byted-marketing-agent-inspiration-insight*" 2>/dev/null | head -1)")
SKILL_DIR=$(dirname "$SCRIPTS_DIR")

# 1. 创建虚拟环境（仅首次）
python3 -m venv $SKILL_DIR/venv

# 2. 安装依赖
$SKILL_DIR/venv/bin/pip install 'volcengine-python-sdk>=4.0.43'

Known defect reminder: volcengine-python-sdk versions 4.0.1 to 4.0.42 (inclusive) have a defect in the built-in retry mechanism. It is strongly recommended to use >=4.0.43.

If the system lacks python3-venv：apt update && apt install python3-venv -y, then re-execute the above steps.

B. Online self-check (after self-check A passes, verify interface connectivity)

SCRIPTS_DIR=$(dirname "$(find ~ -maxdepth 8 -name "openapi_client.py" -path "*byted-marketing-agent-inspiration-insight*" 2>/dev/null | head -1)")
SKILL_DIR=$(dirname "$SCRIPTS_DIR")
VENV_PY=$SKILL_DIR/venv/bin/python3

# 若用户提供了凭证，附加 --ak / --sk；否则省略
$VENV_PY $SCRIPTS_DIR/openapi_client.py --format text \
  ${VOLC_AK_INPUT:+--ak "$VOLC_AK_INPUT"} ${VOLC_SK_INPUT:+--sk "$VOLC_SK_INPUT"} \
  list-industries

To further verify list query:

$VENV_PY $SCRIPTS_DIR/openapi_client.py --format text \
  ${VOLC_AK_INPUT:+--ak "$VOLC_AK_INPUT"} ${VOLC_SK_INPUT:+--sk "$VOLC_SK_INPUT"} \
  query \
  --category "{从行业枚举中选择一个}" \
  --query-type hot_video \
  --task-date "2026-03-12" \
  --page 1 \
  --page-size 5

Goal

Provide users with the "Creative Inspiration Insights" capability:

1. Obtain the queryable industry enum via "Interface 1" (industries only, excluding type).
2. After the user selects an industry, use this Skill's fixed type to query the inspiration insights list under that industry.
3. After the user clicks a record, retrieve the details by unique key (optional: expand from the list context or query the details again).

Interaction logic (mandatory)

When this Skill is triggered: you must proactively call Interface 1 first to obtain the latest industry enum (regardless of whether the user has already provided an industry).

Step 1: Industry enum (shared Interface 1)

• When the user has not specified an industry: first obtain the industry list and let the user choose.
• When the user has specified an industry: refreshing the industry list is still allowed when necessary for validation/correction.

Call the script via Bash (must use the virtual environment Python):

$VENV_PY \
  $SCRIPTS_DIR/openapi_client.py \
  ${VOLC_AK_INPUT:+--ak "$VOLC_AK_INPUT"} ${VOLC_SK_INPUT:+--sk "$VOLC_SK_INPUT"} \
  --format text list-industries

Step 2: Query by industry (type is fixed and controlled by this Skill)

• This Skill's query_type is fixed to hot_video(do not expose/ask the user for type).
• Always use --format json; the script returns the complete fields, and you are responsible for formatting and displaying them.
• Sort by 播放量 DESCby default (play count descending); the user may specify sorting by other fields.

YESTERDAY=$(date -v-1d +%Y-%m-%d 2>/dev/null || date -d "yesterday" +%Y-%m-%d)
$VENV_PY \
  $SCRIPTS_DIR/openapi_client.py --format json \
  ${VOLC_AK_INPUT:+--ak "$VOLC_AK_INPUT"} ${VOLC_SK_INPUT:+--sk "$VOLC_SK_INPUT"} \
  query \
  --category "{industry_name}" \
  --query-type hot_video \
  --task-date "$YESTERDAY" \
  --order-by "播放量 DESC" \
  --page 1 \
  --page-size 20

When the user requests sorting by other dimensions, replace the value of --order-by , for example:

• "点赞数 DESC" — most liked
• "评论数 DESC" — most commented
• "分享数 DESC" — most shared
• "5秒完看率 DESC" — highest 5-second completion rate
• "完播次数 DESC" — most complete views

After returning the list results each time, proactively inform the user which fields they can sort by. Example guidance:

💡 Currently sorted by play count. You can also ask me to sort by "likes", "comments", "shares", or "5-second completion rate".

Step 3: Detail expansion (optional)

YESTERDAY=$(date -v-1d +%Y-%m-%d 2>/dev/null || date -d "yesterday" +%Y-%m-%d)
$VENV_PY \
  $SCRIPTS_DIR/openapi_client.py --format json \
  ${VOLC_AK_INPUT:+--ak "$VOLC_AK_INPUT"} ${VOLC_SK_INPUT:+--sk "$VOLC_SK_INPUT"} \
  query \
  --category "{industry_name}" \
  --query-type hot_video \
  --task-date "$YESTERDAY" \
  --filter "视频ID = '{item_id}'" \
  --page 1 \
  --page-size 1

Data field descriptions

Each record returned by the interface is a viral video,all passed through without trimming：

Field name	Meaning
Video ID	Unique video ID
Title	Video title
Creation date	Video creation date
Link	Douyin video link
Play count	Cumulative play count
Like count	Cumulative like count
Comment count	Cumulative comment count
Share count	Cumulative share count
Follow count	Cumulative follow count
Favorite count	Cumulative favorite count
Organic traffic play count	Organic traffic play count
Soft ad play count	Soft ad play count
Hard ad play count	Hard ad play count
5-second completion rate	5-second completion rate
Complete view count	Complete view count
Skip count	Total play count that was skipped
Business type	Business type tag
Speech text	Video speech-to-text (ASR)
On-screen text	Video on-screen text (OCR)
Polished copy	Polished speech text
Video analysis	Multimodal video shot-by-shot analysis (JSON)
Analysis prompt	Prompt for generating video analysis
Storyboard script	Storyboard script prompt
Keyframe screenshots	Keyframe screenshot URLs (JSON)
Replication prompt	Generation prompt for replicating the video (JSON)
Daily plays / daily likes, etc.	Daily plays/likes/comments/shares/follows
Production date	Task run end date
Task name / industry / task date	Task metadata

Display specifications

⛔ ProhibitedAdd any content outside the structure specified by the template below, including introductions, summaries, personal analysis, or additional explanations. Directly pasting raw JSON is prohibited.

List view (fixed template, columns and order cannot be changed)

## 📊 {行业} 热门视频（{task_date}）｜按{排序字段中文名}排序

| # | 标题 | 播放量 | 点赞 | 5秒完看率 | 完播 | 链接 |
|---|------|--------|------|-----------|------|------|
| 1 | {标题} | {播放量}万 | {点赞数}万 | {5秒完看率}% | {完播次数}万 | [▶](url) |
...

💡 你可以继续问我：
- {引导问题1}
- {引导问题2}
- {引导问题3}

Numeric rules: keep 1 decimal place; if less than 10,000, display the original value; truncate titles over 20 characters and add "…";url When empty, display "—".

Detail view (flexibility retained)

Select display fields according to the user's question intent, but must follow:

• Start with the video title as an H3 heading
• 关键帧截图 For images use ![](url) embedded
• 视频分析、复刻提示词 and other JSON fields, parse them and display according to content logic
• 润色文案、分镜脚本 and other long texts in full, without truncation

Intent → priority field mapping:

The user is asking about…	Priority display
Storyboard / script	分镜脚本
What was said / lines / copy	润色文案
Keyframes / screenshots	关键帧截图(images embedded)
Replication / generation prompt	复刻提示词
Video analysis / shots	视频分析
View all / details	All non-empty fields, displayed in order according to the table above

3 guiding questions must be attached at the end.

Guiding question specifications (must be executed after each returned result)

After each business result output, 2–3 guiding questions must be attached at the end, to help users explore further. The guiding questions should be dynamically generated based on the current result content, and should not be the same every time.

After returning the industry list

💡 You can continue asking me:

• "Help me look upbeautyindustry creative inspiration insights"
• "I want to seeapparelindustry's recent hit creatives"

After returning the insights list

💡 You can continue asking me:

• "Help me expand the detailed analysis of item 1" (or name a specific title)
• "What is the storyboard prompt for this video?"
• "Help me look at its keyframe screenshots"
• "Switch to another industry to look for creative inspiration"

After returning a single detail,

💡 You can continue asking me:

• "Give me the complete storyboard prompt for this one"
• "Look at the other ideas in the list"
• "Switch tofoodindustry and check whether there are hit posts in a similar style"

Principle: the guiding question must be specific (include the current industry name, video title, or field name), so that the user feels they can continue exploring by simply replying.

Parameter rules

• industry_name: a user-perceivable dimension; it must come from the industry enumeration returned by API 1 (or be consistent with it).
• task_date: by default take T-1 (yesterday), i.e. $(date -v-1d +%Y-%m-%d 2>/dev/null || date -d "yesterday" +%Y-%m-%d); if the user specifies a date, the user's choice prevails.
• type：Forbidden to deliver from API 1; it is fixed internally by this Skill as inspiration_insight。

Error handling

• API call failure: output only a brief failure reason to the user (do not include URL/Token/script name/stack).
• Missing industry: output the industry candidate list (appropriately truncated) and let the user choose.
• No data: output "This industry currently has no inspiration insight data".

Credential description (for execution use only; forbidden to echo back to the user)

Volcengine SDK authentication (required for API calls)

This Skill uses volcenginesdkcore.ApiClient to send a signed request to cdp-saas.cn-beijing.volcengineapi.com . Action: ArkOpenClawSkill，Version: 2022-08-01。

Credentialsobtained only through user input, priority:--ak/--sk parameter > environment variable VOLCENGINE_ACCESS_KEY/VOLCENGINE_SECRET_KEY。

• VOLCENGINE_ACCESS_KEY：AccessKey
• VOLCENGINE_SECRET_KEY：SecretKey
• VOLC_SERVICE: override the Service name (optional, default cdp_saas）
• VOLCENGINE_REGION: override Region (optional, default cn-beijing）

Optional overrides

• PUBLIC_INSIGHT_API_URL: override the default endpoint (for internal debugging only)

Security requirement: it is forbidden to hard-code plaintext AK/SK in SKILL.md or in code.