Imported from DivXPro/analyze-cli (SKILL.md). Install upstream with npx skills add DivXPro/analyze-cli. Copyright stays with the author.

analyze-cli Skill

You operate the analyze-cli command-line tool for social media content analysis.

Pre-execution Checks

Run these in order before any workflow:

1. Verify CLI is executable: analyze-cli --version
2. Ensure daemon is running: analyze-cli daemon status → analyze-cli daemon start if needed
3. Read opencli skill before using any opencli command
4. Verify opencli: opencli --help or opencli doctor

If daemon logs a health-check failure and exits, do not delete the database file. Ensure no other process holds the database lock, then restart the daemon.

Capabilities by Phase

Phase 1: Data Collection

Phase 2: Task Setup

Phase 3: Data Preparation

Phase 4: Analysis Execution

Progress output (--wait mode):

[10:23:45] Step: sentiment-analysis | running | 15/30 done, 1 failed
[10:24:45] Steps progress: 2/2 completed

Phase 5: Results & Management

Utility & Recovery

Advanced: Create Strategy

Execution Modes

Both task prepare-data and task run-all-steps / task step run support two execution modes. Choose based on whether the user wants to wait for completion or move on:

prepare-task-data is always blocking (it has no --no-wait flag). run-all-steps and step run default to --wait.

Standard Workflow

Data preparation and analysis are executed back-to-back in the standard flow:

search_posts(query) → add_platform(if new) → create_task(with fetch_note template)
  → import_posts(with --task-id) → add_step_to_task(for each strategy)
  → prepare_task_data(blocks until done)
  → run_all_steps --wait(blocks until all steps complete, prints progress)
  → get_task_results

Template Discovery (Dynamic Query)

Since OpenCLI supports 100+ platforms and commands change over time, always discover the correct commands dynamically instead of relying on hard-coded examples.

Step 1: Find the site name

opencli list | grep -i <platform_name>
# e.g., opencli list | grep -i xiaohongshu → xiaohongshu

Step 2: Discover available commands

opencli <site> --help
# e.g., opencli xiaohongshu --help → search, note, comments, download, ...

Step 3: Check command signature (critical!)

opencli <site> <command> --help
# e.g., opencli xiaohongshu note --help
# Output: "note-id  Full Xiaohongshu note URL with xsec_token"
#         → requires {url} variable

Step 4: Build templates based on command signature

• If help says "<note-id>" or "<post-id>" (short ID) → use {note_id}
• If help says "Full URL" or "URL" → use {url} (always preferred when ambiguous)

Template Variables

Rule of thumb: When in doubt, use {url}. It is the most universally accepted format across platforms.

Example: Full Analysis Flow (Dynamic Discovery)

# 1. Discover platform commands
opencli list | grep -i xiaohongshu        # → xiaohongshu
opencli xiaohongshu --help                # → search, note, comments, ...
opencli xiaohongshu note --help           # → requires "Full note URL"

# 2. Search
opencli xiaohongshu search "上海美食" --limit 10 -f json > posts.json

# 3. Setup
analyze-cli platform add --id xhs --name "小红书"
analyze-cli task create --name "上海美食分析" \
  --cli-templates '{"fetch_note":"opencli xiaohongshu note {url} -f json","fetch_comments":"opencli xiaohongshu comments {url} --limit 100 -f json"}'

# 4. Import
analyze-cli post import --platform xhs --file posts.json --task-id <task_id>

# 5. Add strategies
analyze-cli task step add --task-id <task_id> --strategy-id sentiment-topics --name "情感分析"
analyze-cli task step add --task-id <task_id> --strategy-id risk-detection --name "风险检测"

# 6. Prepare data (blocks, resumable)
analyze-cli task prepare-data --task-id <task_id>

# 7. Run analysis (blocks with progress output)
analyze-cli task run-all-steps --task-id <task_id>
# → [10:23:45] Steps progress: 0/2 completed | running: 情感分析
# → [10:24:12] Steps progress: 1/2 completed | running: 风险检测
# → [10:24:45] Steps progress: 2/2 completed

# 8. Results
analyze-cli task results --task-id <task_id>

Alternative: Non-blocking Mode

If the user wants to start the analysis and check back later (e.g., running multiple tasks in parallel):

# Data preparation still blocks
analyze-cli task prepare-data --task-id <task_id>

# But analysis runs in background
analyze-cli task run-all-steps --task-id <task_id> --no-wait
# → "All steps processed" (returns immediately)

# Check status later
analyze-cli task status --task-id <task_id>

Recovery from Failure

# If a step fails after all retries:
analyze-cli task step reset --task-id <tid> --step-id <sid>
analyze-cli task step run --task-id <tid> --step-id <sid> --wait

JSON Rules for create_strategy

Required fields:

• id: lowercase a-z0-9_-, e.g. monetization-v1
• name, version (default "1.0.0")
• target: "post" only
• needs_media: { enabled: true/false, media_types, max_media, mode } if enabled
• prompt: must include {{content}}; include {{media_urls}} if needs_media.enabled
• output_schema: standard JSON Schema, type: "object", each property needs type

Prompt variables (whitelist only):

• {{content}} (required), {{title}}, {{author_name}}, {{platform}}, {{published_at}}, {{tags}}, {{media_urls}}

Do NOT use {{likes}}, {{collects}}, {{comments}}, etc. They are not substituted.

Prompt quality: Append a JSON output-format hint to ensure pure JSON response (no markdown code blocks).

Example:

{
  "id": "monetization-v1",
  "name": "Monetization Potential",
  "version": "1.0.0",
  "target": "post",
  "needs_media": { "enabled": true, "media_types": ["image"], "max_media": 5, "mode": "all" },
  "prompt": "Analyze the monetization potential of this post.\n\nContent: {{content}}\nAuthor: {{author_name}}\n\n{{media_urls}}\n\nReturn pure JSON only: { \"score\": number, \"category\": string }",
  "output_schema": {
    "type": "object",
    "properties": {
      "score": { "type": "number" },
      "category": { "type": "string" }
    }
  }
}

Error recovery for strategy import:

• Validation fails → read exact error, fix field, retry (max 2 retries)
• Same version exists → ask to bump version or change ID
• After approval: analyze-cli strategy import --json '<json>', then analyze-cli strategy show --id <id>

Global Rules

1. Never write temporary polling scripts looping analyze-cli task status. Use built-in --wait mode.
2. Never use direct database access (e.g., node -e scripts opening DuckDB). Always use CLI commands.
3. Rate limit (429) recovery: workers auto-requeue with exponential backoff. Only intervene when status becomes failed after all retries.
4. Platform check first: always analyze-cli platform list before platform add to avoid "already exists" errors.
5. Do NOT manually fetch note details before import: let prepare-data handle enrichment via the fetch_note template.