SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsxiaohongshu-weeklytop

xiaohongshu-weeklytop

General & other

View repository

Updated 10-16 01:48

About this skill

Xiaohongshu Seven-Day Viral Notes

Overview

One-Sentence Positioning: A Xiaohongshu seven-day viral notes tool designed specifically for content creators and operations personnel, enabling one-click access to popular notes and in-depth analysis in vertical fields.

Core Value：

  • Solves the topic selection challenge of "not knowing what content is currently trending and why it's trending"
  • Provides seven-day viral notes + intelligent analysis + optional HTML reports to support reviews and creative decisions
  • Supports automatic keyword matching across 24 vertical categories (the original "Comprehensive Miscellaneous" has been reclassified under "Comprehensive All"), lowering the query threshold

Target Users: Brands, MCN agencies, Xiaohongshu bloggers, content operations, growth teams

Technical Foundation: Python 3 + RedFox Xiaohongshu Data API, data updated daily at 19:00

Features

🎯 Core Features

Feature Description
📊 Recent Trending Query Query popular notes by category, covering 24 vertical fields including beauty, fashion, food, home, etc., to quickly grasp current traffic trends
📈 Seven-Day Popularity Analysis Based on in-depth insights from the top 50 popular notes in each category over the past 7 days, breaking down the common traits of viral hits from dimensions such as trending styles, in-depth analysis of hot topics, and practical value
🔍 Format Pattern Comparison Automatically identifies viral elements such as high-quality covers, emotional resonance points, practical value, and timely trending topics, distilling reusable creative paradigms
📁 Creative Suggestion Output Based on analysis results, provides actionable topic directions, differentiation strategies, and suggestions for breaking down high-level works
🔔 Subscription Push Scheduled push of the latest trend analysis reports, continuously tracking niche hot topics so no traffic opportunity is missed

✨ Highlights

  • ⚡ Data Consistency: The seven-day viral notes table and the HTML page use the same data source and sorting logic, with completely consistent rankings
  • 📱 Paginated Display: Initially displays TOP20; reply "View More" to load the remaining data
  • 🎯 Under-the-Radar Viral Hits: Focuses on low-follower, high-engagement notes, suitable for discovering benchmark samples
  • 🔒 Zero-Configuration Calling: The agent automatically determines the query date during execution, with no manual maintenance required

Authentication

Get API Key

  1. Visit RedFox Hub Official Website to learn more about the service
  2. Go to Registration Page to register an account
  3. Newly registered users will receive free credits and can immediately start using the API service
  4. After registering and logging in, obtain the API Key in the personal center, in the format ak_xxxxxxxx

Configure API Key

REDFOX_API_KEY Retrieved from environment variables, format ak_xxxxxxxx。

If not set, prompt the user to configure it themselves:export REDFOX_API_KEY=<你的apikey>; if they don't know how to configure it, the agent can proactively help the user set it up:

  • macOS/Linux: Append export REDFOX_API_KEY=<值> to ~/.zshrc(zsh) or ~/.bashrc(bash), then source the corresponding file to make it globally effective
  • Windows: use [Environment]::SetEnvironmentVariable("REDFOX_API_KEY", "<值>", "User") to set a user-level permanent environment variable (requires restarting the terminal to take effect)

After configuration is complete, verify:echo $REDFOX_API_KEY(macOS/Linux) or echo %REDFOX_API_KEY%(Windows), to ensure that switching to another skill can also read it.

One-click installation

Prerequisites

  • Python 3.8+
  • Network can access the redfox.hk data API
  • Installed requests library (pip install requests）
  • Configured REDFOX_API_KEY environment variable (see the "Authentication" section above)

Installation method

Method 1: WorkBuddy / Cursor Skills (recommended)

  1. Place this Skill directory in the Skills workspace (e.g., ~/.workbuddy/skills/xiaohongshu-weeklytop）
  2. Ensure the directory structure is complete:SKILL.md、references/、scripts/
  3. Trigger directly in the conversation, for example:
    • "Help me look up viral posts related to mascara"
    • "What popular content is there on Xiaohongshu recently"
    • "View the seven-day hot list in the fashion domain"

Method 2: Run independently from the command line

# 进入 Skill 目录
cd xiaohongshu-weeklytop

# 获取榜单数据（JSON 输出）
python scripts/xhs_weekly_fetcher.py --keyword "睫毛膏" --top_n 50

# 生成 HTML 报告（从已获取的数据文件读取，不再调用API）
python scripts/gen_xhs_html.py --data_file "xhs_data.json" --category "化妆美容" --top 20

Usage guide

Execution constraints (mandatory): When the Agent executes this Skill,it must first fully read and strictly follow references/core_workflow.md the calling Key instructions, output specifications, operation steps, and precautions in it. The following is a summary of basic usage; the detailed process is subject to the core workflow document.

Basic usage

1. Keyword search for viral posts

User: Help me look up viral posts related to mascara

Assistant: Automatically match the "Makeup & Beauty" category → retrieve TOP50 data → output the seven-day viral posts TOP20 → seven-day analysis → feature inquiry (HTML + subscription)

2. Keyword does not match exactly (v2.0)

User: Look up viral posts related to bathhouses

Assistant: The keyword does not hit any category keyword → direct query is prohibited → display recommended similar categories (1~3, by relevance, only strongly related ones, no forced matching) + "⚠️If there is no category you want to query, you can go to the https://redfox.hk/apis/xiaohongshu/384C6W6B?source=github API documentation to query more precise works~" option → wait for the user to confirm the category(after confirmation, re-query with the specified category) or choose "If there is none..." (stop all subsequent processes）

3. Broad-domain popular query

User: What popular content is there on Xiaohongshu recently

Assistant: Use the "All Comprehensive" category → output the complete results in the standard three steps

4. View more data

User: View more

Assistant: Continue outputting from TOP21 to the end → if the user chooses to generate HTML, read the complete data from the already retrieved data file and regenerate

Advanced usage

1. Query by specified date

User: View the fashion domain hot list for 2026-04-15

Assistant: Use --rank_date "2026-04-15" to query data for a specified date

2. Directly specify the category

python scripts/xhs_weekly_fetcher.py --category "时尚穿搭" --top_n 50
python scripts/gen_xhs_html.py --category "时尚穿搭" --top 50

3. Subscribe to daily push / generate HTML

After the first query is completed, the assistant will display a feature prompt: reply 1 to subscribe to the daily 19:30 push, reply 2 to generate a Xiaohongshu-style HTML file package. After the HTML is generated, it will automatically be previewed in the conversation (preferring preview_url, and if it does not display properly, use open_result_view as a fallback), with no need to manually find the file.

4. Custom HTML output path

python scripts/gen_xhs_html.py --data_file "xhs_data.json" --category "穿搭" --top 20 --output ./reports/小红书七日爆款笔记_穿搭.html

Common Commands Quick Reference

Command / Scenario Function
python scripts/xhs_weekly_fetcher.py --keyword "{词}" --top_n 50 Get the raw ranking data
python scripts/gen_xhs_html.py --data_file "{文件}" --category "{分类}" --top 20 Generate HTML for the first time (TOP20, read from the data file)
python scripts/gen_xhs_html.py --data_file "{文件}" --category "{分类}" --top 50 Generate the complete HTML after viewing more
User says "view more" Output TOP21+
User replies 1 / "subscribe" Subscribe to the daily 19:30 push
User replies 2 / "html" / "generate" Generate HTML file package

Core Workflow Reference

For the complete execution specification (output format, calling Key, table fields, data consistency, subscription logic, usage examples, etc.), see:

→ references/core_workflow.md

Use Cases

Scenario 1: Blogger Topic Inspiration

Role: Xiaohongshu new blogger

Need: Understand what content in the same niche is currently likely to go viral

How to Use：

  1. Enter niche keywords (such as "skincare" or "outfit")
  2. View the TOP20 viral notes of the past seven days and the seven-day analysis
  3. Benchmark the title structure and content characteristics of reference notes

Expected Benefits: Quickly find topic directions worth learning from and reduce the trial-and-error cost of cold start

Scenario 2: Brand Competitor Monitoring

Role: Brand marketing manager

Need: Monitor viral content and trend changes in vertical fields

How to Use：

  1. Query by product/category keywords (such as "lipstick" or "sunscreen")
  2. Analyze the common characteristics of the highest-engagement works
  3. Export an HTML report for team review

Expected Benefits: Grasp category content trends and optimize advertising and seeding strategies

Scenario 3: MCN Creator Operations Review

Role: MCN operations staff

Need: Provide niche hotspot references for affiliated creators

How to Use：

  1. Query the seven-day hot list by creator niche
  2. Break down viral title types and posting patterns
  3. Subscribe to daily pushes and continuously track hotspots

Expected Benefits: Improve creators' content planning efficiency and shorten the topic discussion cycle

Scenario 4: Growth Team Data Insights

Role: Growth/data analysis colleagues

Need: Obtain an exportable structured hot list report

How to Use：

  1. Query the complete TOP50 of the target category
  2. Use the HTML page to export PDF/images
  3. Combine newly added engagement data to judge the upward momentum of content

Expected Benefits: Obtain shareable and archivable data reports to support weekly reports and strategy meetings

Project Architecture

Directory Structure

xiaohongshu-weeklytop/
├── SKILL.md                      # Skill 入口与使用说明（本文件）
├── references/
│   └── core_workflow.md          # 核心执行流程与输出规范（Agent 必读）
└── scripts/
    ├── xhs_weekly_fetcher.py     # 榜单数据获取脚本
    └── gen_xhs_html.py           # HTML 可视化报告生成脚本

Tech Stack

Item Description
Runtime Environment Python 3.8+
HTTP Requests requests(Native Python)
Data Source RedFox Xiaohongshu Coze Skill API
Output Format Markdown table + standalone HTML file
Deployment Platform WorkBuddy / Cursor Agent Skills

Core Modules

Module File Responsibility
Data Acquisition xhs_weekly_fetcher.py Call API, category matching, date determination, sorted output
Report Generation gen_xhs_html.py Render HTML pages from acquired JSON data files, support PDF/image export
Execution Specifications core_workflow.md Define mandatory constraints such as output format, Key invocation, three-step process, feature inquiries, etc.

Data Update Rules

  • Update Time: Update yesterday's ranking daily at 19:00
  • Data Range: Top 50 trending notes from the past 7 days
  • Category Coverage: 24 vertical domains (the former "General Miscellaneous" has been categorized into "General All")
  • Date Determination: If current time ≥ 19:00, query yesterday; if < 19:00, query the day before yesterday

Common Q&A

Installation-Related Questions

Q1: Script runtime error ModuleNotFoundError: requests？

A: This dependency is a standard Python HTTP library. Please run pip install requests to install. If running in a virtual environment, ensure the corresponding environment is activated.

Q2: Script shows "REDFOX_API_KEY not found"?

A: Please follow the "Authentication" section above to obtain and configure the API Key. Ensure the environment variable REDFOX_API_KEY is correctly set and its format is ak_xxxxxxxx。

Q3: How to add the Skill to Cursor / WorkBuddy?

A: Place the xiaohongshu-weeklytop folder into the Skills directory; the Agent will automatically match and trigger based on description . Mentioning keywords such as "Xiaohongshu trending" or "viral notes" in the conversation will invoke it.

Usage-Related Questions

Q4: How often is the data updated?

A: Ranking data is updated daily at 19:00 (updating yesterday's data). Subscription push time is 19:30 daily.

Q5: Why does it sometimes query "the day before yesterday" instead of "yesterday"?

A: Before 19:00 on the current day, the latest ranking has not yet been updated, so the system automatically queries the day before yesterday's data. After 19:00, it queries yesterday's data. See core_workflow.md date determination rules.

Troubleshooting

Q6: The seven-day viral notes table is inconsistent with the HTML data?

A: When generating HTML, data is read from the acquired JSON data file, using exactly the same raw data as the table. Check whether a different --top parameter was used.

Q7: API request failed or no data?

A: Troubleshoot using the following steps:

  1. Confirm the network can access RedFox Hub official website
  2. Check whether --rank_date is a valid date
  3. Try changing the keyword or specifying --category
  4. When querying before 19:00, confirm whether the day before yesterday's date should be used

Execution Specifications

Q8: What rules must the Agent follow during execution?

A: Must fully comply with references/core_workflow.md, including but not limited to:

  • Key-call instructions (script parameters and top_n/top value specifications)
  • Three-step output order (seven-day viral notes → analysis → feature inquiry)
  • Do not collapse the output; do not output any files other than HTML
  • First-time TOP20 + view more logic
  • When generating HTML, read from the already-acquired data file; do not call the API again
  • After HTML generation, preview_url must be called to display the page directly in the conversation; if it is not displayed properly, use open_result_view as a fallback
  • The feature inquiry is displayed immediately after the analysis; do not skip it