@tikomni/skills 0.1.2 → 0.1.4

package/.skill-package-allowlist.txt

@@ -1,4 +1,2 @@
 # Skill directories included in distributable .skill packages
-skills/meta-capability
-skills/single-work-analysis
-skills/creator-analysis
+skills/social-media-crawl

package/README.md

@@ -2,10 +2,10 @@
 
 English | [中文](./README.zh-CN.md)
 
-Give AI agents direct access to TikOmni's cross-platform content retrieval and structured analysis capabilities.
+Give AI agents direct access to TikOmni's cross-platform content retrieval and structured data capabilities.
 
 Works with `Codex`, `Claude Code`, and `OpenClaw`.  
-Built for content extraction, single-work analysis, creator analysis, search results, comment threads, rankings, livestreams, and structured outputs.
+Built for content retrieval, structured extraction, ASR text acquisition, structured JSON output, and fact-card persistence.
 
 - Website: https://tikomni.com
 - Dashboard: https://app.tikomni.com
@@ -14,15 +14,15 @@ Built for content extraction, single-work analysis, creator analysis, search res
 
 ## Why This Repo Exists
 
-`TikOmni-Skills` is the agent-facing delivery layer for TikOmni skills.
+`TikOmni-Skills` is the agent-facing delivery layer for TikOmni.
 
-Its purpose is not to be a pile of platform scripts or a few fixed templates. More importantly, it packages TikOmni's core capabilities into installable, composable skills so agents can directly:
+Its purpose is not to be a pile of platform scripts or just a few fixed templates. More importantly, it packages TikOmni's core capabilities into installable, composable skills so agents can directly:
 
 - retrieve single content items, creator pages, and content collections
-- retrieve comment threads, search results, rankings, livestreams, and product pages as concrete platform objects
+- retrieve comment threads, search results, rankings, livestreams, and product pages as concrete objects
 - extract titles, captions, subtitles, transcripts, and structured fields
-- generate normalized JSON outputs and Markdown cards
-- continue with analysis, summaries, and downstream knowledge workflows
+- generate normalized JSON outputs and fact cards
+- pass results into archives, knowledge workflows, or downstream systems
 
 If TikOmni is the cross-platform capability layer, this repository is the layer that makes those capabilities usable by agents.
 
@@ -38,45 +38,36 @@ For the full catalog, see https://docs.tikomni.com
 
 ## What Structured Data You Can Get
 
-Depending on the platform and endpoint, the skills can return:
+Depending on platform and endpoint coverage, the skill can return:
 
 - author or account metadata
 - post or video basic information
 - comments and replies
 - search results, ranking results, livestream information, and commerce-related data
-- engagement metrics such as likes, comments, and shares when available
-- subtitles, transcripts, or caption text when supported
+- engagement metrics such as likes, comments, collects, and shares when available
+- subtitles, transcripts, and caption text when supported
 - extractable media URLs and related assets when supported
 - route and request trace metadata for reproducibility
 
-## Skill Modules
+## More Mature Fixed Pipelines
 
-| Skill | Role | Typical tasks |
-| --- | --- | --- |
-| `meta-capability` | General capability layer | Cross-platform retrieval, route discovery, structured extraction, plus generic execution and fallback for comment threads, search, rankings, livestreams, product pages, and other supported objects |
-| `single-work-analysis` | Single-work specialist skill | Extracting and analyzing one video, note, post, or article |
-| `creator-analysis` | Creator specialist skill | Collecting and analyzing creator pages, channels, and content collections |
+On top of those general capabilities, the repository currently freezes and validates four high-frequency pipelines:
 
-Suggested choices:
+- Douyin single work
+- Douyin creator home
+- Xiaohongshu single work
+- Xiaohongshu creator home
 
-- Want to analyze one content item: install `single-work-analysis`
-- Want to analyze a creator page or content collection: install `creator-analysis`
-- Want to keep a general TikOmni entry point available: install `meta-capability`
-- Not sure which one you need yet: install `all`
-
-## More Mature High-Frequency Flows
+These fixed pipelines are currently the most mature and easiest-to-reuse flows.  
+They matter, but they do not define the full capability boundary of this repository.
 
-On top of the general capability layer, this repository already includes a set of more reusable high-frequency flows.
+## Public Skill
 
-Current areas with the most validation and ongoing iteration include:
+The npm package currently exposes:
 
-- Douyin single-work analysis
-- Xiaohongshu single-work analysis
-- Douyin creator-page analysis
-- Xiaohongshu creator-page analysis
-
-These flows represent the most mature and easiest-to-adopt paths today.  
-They matter, but they do not define the full capability boundary of this repository.
+| Skill | Role |
+| --- | --- |
+| `social-media-crawl` | Cross-platform structured crawling, fixed pipelines, fact-card persistence, and MCP-first generic retrieval |
 
 ## 30-Second Quick Start
 
@@ -96,14 +87,16 @@ First, list the currently available skills:
 npx @tikomni/skills list
 ```
 
+This package currently exposes `social-media-crawl`.
+
 Install into Codex:
 
 ```bash
-# Install all skills
+# Install the public skill
 npx @tikomni/skills install codex all
 
-# Install one specific skill
-npx @tikomni/skills install codex single-work-analysis
+# Equivalent explicit install
+npx @tikomni/skills install codex social-media-crawl
 ```
 
 Default target: `$CODEX_HOME/skills`, default `~/.codex/skills`
@@ -111,11 +104,11 @@ Default target: `$CODEX_HOME/skills`, default `~/.codex/skills`
 Install into Claude Code:
 
 ```bash
-# Install all skills
+# Install the public skill
 npx @tikomni/skills install claude-code all
 
-# Install only the creator-analysis skill
-npx @tikomni/skills install claude-code creator-analysis
+# Equivalent explicit install
+npx @tikomni/skills install claude-code social-media-crawl
 ```
 
 Default target: `~/.claude/skills`
@@ -123,11 +116,11 @@ Default target: `~/.claude/skills`
 Install into OpenClaw:
 
 ```bash
-# Install all skills
+# Install the public skill
 npx @tikomni/skills install openclaw all
 
 # Install into a custom directory
-npx @tikomni/skills install openclaw meta-capability --dir "/custom/skills"
+npx @tikomni/skills install openclaw social-media-crawl --dir "/custom/skills"
 ```
 
 Default target: prefers `~/.openclaw/workspace/skills`, otherwise `~/.openclaw/skills`
@@ -161,20 +154,19 @@ For advanced variables, see [`env.example`](./env.example).
 
 Instead of running commands manually, you can ask your agent directly:
 
-- "Install all TikOmni skills into Codex."
-- "Install `creator-analysis` into the Claude Code skills directory."
-- "Install `meta-capability` into OpenClaw and use `/custom/skills` as the target directory."
+- "Install `social-media-crawl` into Codex."
+- "Install `social-media-crawl` into the Claude Code skills directory."
+- "Install `social-media-crawl` into OpenClaw and use `/custom/skills` as the target directory."
 
 ## How to Use It After Installation
 
 Once configured, you can trigger tasks in natural language, for example:
 
-- "Extract the structured fields and subtitles from this Douyin video."
-- "Analyze this Xiaohongshu note and output a work card plus a content breakdown."
-- "Fetch the latest 20 posts from this Douyin creator page and summarize topic patterns."
-- "Analyze this Xiaohongshu account and output a creator profile with representative content traits."
-- "Search this keyword on Douyin and summarize the top 20 result patterns."
-- "Fetch this livestream's information and return a structured summary."
+- "Extract the structured fields and primary text from this Douyin video."
+- "Fetch this Xiaohongshu note and write a fact card."
+- "Collect works from this creator home and persist them into the author archive."
+- "Use TikOmni MCP to fetch a comment thread and return normalized JSON."
+- "Use TikOmni MCP to fetch search or ranking results and keep the output structured."
 
 ## Versioning and Releases
 

package/README.zh-CN.md

@@ -2,10 +2,10 @@
 
 中文 | [English](./README.md)
 
-让 AI Agent 直接使用 TikOmni 的跨平台内容获取与结构化分析能力。
+让 AI Agent 直接使用 TikOmni 的跨平台内容获取与结构化数据能力。
 
 适用于 `Codex`、`Claude Code`、`OpenClaw`。  
-面向内容抓取、单作品分析、创作者分析、搜索结果、评论线程、榜单、直播间和结构化结果产出。
+面向内容抓取、结构化提取、ASR 文本获取、结构化 JSON 结果和事实卡落盘。
 
 - Website: https://tikomni.com
 - Dashboard: https://app.tikomni.com
@@ -16,19 +16,19 @@
 
 `TikOmni-Skills` 是 TikOmni 面向 AI Agent 的 Skill 交付层。
 
-它的目标不是堆一批平台脚本，也不只是沉淀几个固定模板；它更重要的作用，是把 TikOmni 的原能力组织成 Agent 可安装、可调用、可组合的 Skills，让 Agent 能直接完成：
+它的目标不是堆一批平台脚本，也不只是沉淀几个固定模板；更重要的是把 TikOmni 的原能力组织成 Agent 可安装、可调用、可组合的 Skill，让 Agent 能直接完成：
 
 - 获取单条内容、账号主页和内容集合
 - 获取评论线程、搜索结果、榜单、直播间和商品页等具体对象
 - 提取标题、文案、字幕、转写和结构化字段
-- 输出标准化 JSON 与 Markdown 卡片
-- 基于真实抓取结果继续做分析、总结和归档
+- 输出标准化 JSON 与事实卡
+- 将结果继续接入归档、知识库或后续工作流
 
 如果你把 TikOmni 看作跨平台能力底座，这个仓库就是把这些能力交付给 Agent 的使用层。
 
-## 📦 支持平台
+## 支持平台
 
-当前目录覆盖主流平台（示例）：
+当前能力覆盖主流平台（示例）：
 
 - 抖音、小红书、快手、B站、微博
 - TikTok、YouTube、Instagram、Threads、Twitter/X、Reddit、LinkedIn
@@ -36,47 +36,38 @@
 
 完整列表见官方文档目录：https://docs.tikomni.com
 
-## 🧩 可获取哪些结构化数据
+## 可获取哪些结构化数据
 
-按不同平台/接口可返回：
+按不同平台和接口能力，可返回：
 
 - 作者/账号信息
 - 作品/视频基础信息
 - 评论与回复数据
 - 搜索结果、榜单结果、直播间信息、商品相关数据
-- 互动指标（点赞、评论、分享等，视接口可用性）
-- 字幕/转写/文案文本（接口支持时）
+- 互动指标（点赞、评论、收藏、分享等，视接口可用性）
+- 字幕、转写、文案等文本字段（接口支持时）
 - 媒体地址等可提取资源（接口支持时）
-- 路由与请求追踪信息（方便复现）
+- 路由与请求追踪信息（方便复现和归档）
 
-## Skill 模块
+## 当前更成熟的固定 Pipeline
 
-| Skill | 作用 | 典型任务 |
-| --- | --- | --- |
-| `meta-capability` | 通用能力层 | 跨平台获取、路由探索、结构化抓取，以及评论线程、搜索、榜单、直播间、商品页等对象的通用执行与兜底 |
-| `single-work-analysis` | 单作品专项 Skill | 单个视频、单篇笔记、单条帖子、单篇文章的提取与分析 |
-| `creator-analysis` | 创作者专项 Skill | 账号主页、作者页、频道页、内容集合的抓取与聚合分析 |
+在这些通用能力之上，当前已经固定并重点验证了 4 条高频 pipeline：
 
-选择建议：
+- 抖音作品
+- 抖音主页
+- 小红书作品
+- 小红书主页
 
-- 想分析单个内容对象：安装 `single-work-analysis`
-- 想分析账号主页或内容集合：安装 `creator-analysis`
-- 想保留通用 TikOmni 能力入口：安装 `meta-capability`
-- 不确定会用到哪些场景：直接安装 `all`
-
-## 当前更成熟的高频链路
+这些固定 pipeline 是当前更成熟、可直接复用的高频链路。  
+它们很重要，但不等于本仓库能力边界的全部定义。
 
-在通用能力层之上，本仓库已经沉淀出一批更适合直接复用的高频方案。
+## 对外 Skill
 
-当前重点验证和持续打磨的方向包括：
+当前 npm 包对外公开的 Skill 为：
 
-- Douyin 单作品分析
-- Xiaohongshu 单作品分析
-- Douyin 创作者主页分析
-- Xiaohongshu 创作者主页分析
-
-这些链路代表当前最成熟、最适合直接上手的实践路径。  
-它们很重要，但不等于本仓库能力边界的全部定义。
+| Skill | 作用 |
+| --- | --- |
+| `social-media-crawl` | 跨平台结构化抓取、固定 pipeline、事实卡入库、MCP-first 通用调用 |
 
 ## 30 秒快速开始
 
@@ -96,14 +87,16 @@
 npx @tikomni/skills list
 ```
 
+当前 npm 包对外提供 `social-media-crawl`。
+
 安装到 Codex：
 
 ```bash
-# 安装全部 Skills
+# 安装公开 Skill
 npx @tikomni/skills install codex all
 
-# 只安装一个 Skill
-npx @tikomni/skills install codex single-work-analysis
+# 显式安装同一个 Skill
+npx @tikomni/skills install codex social-media-crawl
 ```
 
 默认目录：`$CODEX_HOME/skills`，默认值 `~/.codex/skills`
@@ -111,11 +104,11 @@ npx @tikomni/skills install codex single-work-analysis
 安装到 Claude Code：
 
 ```bash
-# 安装全部 Skills
+# 安装公开 Skill
 npx @tikomni/skills install claude-code all
 
-# 只安装创作者分析 Skill
-npx @tikomni/skills install claude-code creator-analysis
+# 显式安装同一个 Skill
+npx @tikomni/skills install claude-code social-media-crawl
 ```
 
 默认目录：`~/.claude/skills`
@@ -123,11 +116,11 @@ npx @tikomni/skills install claude-code creator-analysis
 安装到 OpenClaw：
 
 ```bash
-# 安装全部 Skills
+# 安装公开 Skill
 npx @tikomni/skills install openclaw all
 
 # 安装到自定义目录
-npx @tikomni/skills install openclaw meta-capability --dir "/custom/skills"
+npx @tikomni/skills install openclaw social-media-crawl --dir "/custom/skills"
 ```
 
 默认目录：优先 `~/.openclaw/workspace/skills`，否则 `~/.openclaw/skills`
@@ -161,20 +154,19 @@ TIKOMNI_CARD_ROOT="/absolute/path/to/tikomni-cards"
 
 除了手动执行命令，你也可以直接对 Agent 说：
 
-- “帮我把 TikOmni skills 全部安装到 Codex。”
-- “把 `creator-analysis` 安装到 Claude Code 的 skills 目录。”
-- “把 `meta-capability` 安装到 OpenClaw，目标目录是 `/custom/skills`。”
+- “把 `social-media-crawl` 安装到 Codex。”
+- “把 `social-media-crawl` 安装到 Claude Code 的 skills 目录。”
+- “把 `social-media-crawl` 安装到 OpenClaw，目标目录是 `/custom/skills`。”
 
 ## 安装完成后怎么用
 
 配置完成后，可以直接通过自然语言发起任务，例如：
 
-- “提取这个抖音视频的结构化信息和字幕。”
-- “分析这个小红书笔记，输出作品卡和内容拆解。”
-- “抓取这个抖音主页近 20 条内容，并总结选题方向。”
-- “分析这个小红书账号，输出作者画像和代表性内容特征。”
-- “搜索这个关键词下的抖音结果，并整理前 20 条内容特征。”
-- “获取这个直播间的信息并输出结构化摘要。”
+- “提取这个抖音视频的结构化字段和主文本。”
+- “抓取这个小红书作品并写入事实卡。”
+- “抓取这个主页的作品并持续入库到作者目录。”
+- “通过 TikOmni MCP 获取这个评论线程并输出标准 JSON。”
+- “通过 TikOmni MCP 获取搜索或榜单结果，并保持结构化返回。”
 
 ## 版本与发布
 

package/bin/tikomni-skills.js

@@ -16,8 +16,8 @@ function printUsage() {
 示例:
   tikomni-skills list
   tikomni-skills install codex all
-  tikomni-skills install claude-code creator-analysis
-  tikomni-skills install openclaw meta-capability --dir "/custom/skills"
+  tikomni-skills install codex social-media-crawl
+  tikomni-skills install openclaw social-media-crawl --dir "/custom/skills"
 `);
 }
 

package/env.example

@@ -29,7 +29,7 @@ TIKOMNI_CARD_ROOT="/absolute/path/to/tikomni-cards"
 
 
 # =========================================================
-# Common runtime / 通用运行参数
+# Common optional runtime / 通用可选运行参数
 # =========================================================
 
 # [ZH] TikOmni API 基础地址。默认值：https://api.tikomni.com
@@ -62,7 +62,7 @@ TIKOMNI_HTTP_ACCEPT_LANGUAGE="zh-CN,zh;q=0.9,en;q=0.8"
 
 
 # =========================================================
-# Output directory model / 结果输出目录模型
+# Output directories / 结果输出目录
 # =========================================================
 
 # [ZH] 运行中间产物目录名，位于 TIKOMNI_OUTPUT_ROOT 下。默认值：_runs
@@ -79,57 +79,55 @@ TIKOMNI_OUTPUT_ERRORS_DIR="_errors"
 
 
 # =========================================================
-# Card routing / 卡片落盘路由
+# Card routing and naming / 卡片落盘路由与命名
 # =========================================================
 
 # [ZH] 路由语言预设。默认值：zh
 # [EN] Route locale preset. Default: zh
 TIKOMNI_PATH_LOCALE="zh"
 
-# [ZH] 作品卡文件名前缀。默认值：CBV
-# [EN] Work card filename prefix. Default: CBV
-TIKOMNI_CARD_PREFIX_WORK="CBV"
-
-# [ZH] 作者卡文件名前缀。默认值：CBA
-# [EN] Author card filename prefix. Default: CBA
-TIKOMNI_CARD_PREFIX_AUTHOR="CBA"
-
-# [ZH] 作者样本卡文件名前缀。默认值：CBV
-# [EN] Author sample card filename prefix. Default: CBV
-TIKOMNI_CARD_PREFIX_AUTHOR_SAMPLE_WORK="CBV"
-
-# [ZH] 卡片文件名模板。默认值：{prefix}-{author_slug}-{title_slug}{ext}
-# [EN] Card filename pattern. Default: {prefix}-{author_slug}-{title_slug}{ext}
-TIKOMNI_FILENAME_PATTERN_CARD="{prefix}-{author_slug}-{title_slug}{ext}"
+# [ZH] 卡片文件名模板。默认值：{identifier}{ext}
+# [EN] Card filename pattern. Default: {identifier}{ext}
+# [ZH] 当前可用占位符：identifier / platform / author_slug / ext
+# [EN] Supported placeholders: identifier / platform / author_slug / ext
+TIKOMNI_FILENAME_PATTERN_CARD="{identifier}{ext}"
 
 # [ZH] JSON 结果文件名模板。默认值：{timestamp}-{platform}-{identifier}{ext}
 # [EN] JSON output filename pattern. Default: {timestamp}-{platform}-{identifier}{ext}
 TIKOMNI_FILENAME_PATTERN_JSON="{timestamp}-{platform}-{identifier}{ext}"
 
-# [ZH] 兼容旧变量，仅影响卡片文件名，不推荐继续使用。默认值：空
-# [EN] Legacy compatibility variable, only affects card filenames, not recommended. Default: empty.
-# TIKOMNI_FILENAME_PATTERN="{prefix}-{author_slug}-{title_slug}{ext}"
+# [ZH] 显式覆盖作品事实卡目录路由，使用 "|" 分隔层级。默认值：空。
+# [EN] Explicit work-fact-card route override, using "|" as separator. Default: empty.
+# [ZH] zh 默认：内容系统|作品库|{platform}-{author_slug}
+# [EN] zh preset default: 内容系统|作品库|{platform}-{author_slug}
+# [EN] en preset default: content-system|work-library|{platform}-{author_slug}
+# TIKOMNI_CARD_ROUTE_WORK="内容系统|作品库|{platform}-{author_slug}"
+
+# [ZH] 兼容旧变量。仍可覆盖作品事实卡目录，但不推荐新配置继续使用。
+# [EN] Legacy compatibility variable. Still overrides the work-fact-card route, but not recommended for new setups.
+# TIKOMNI_CARD_ROUTE_AUTHOR_SAMPLE_WORK="内容系统|作品库|{platform}-{author_slug}"
+
 
-# [ZH] 显式覆盖作品卡目录路由，使用 "|" 分隔层级。默认值：空。
-# [EN] Explicit work-card route override, using "|" as separator. Default: empty.
-# [ZH] zh 默认：内容系统|对标研究|作品卡
-# [EN] zh preset default: 内容系统|对标研究|作品卡
-# [EN] en preset default: content-system|benchmark-research|work-cards
-# TIKOMNI_CARD_ROUTE_WORK="content-system|benchmark|work-cards"
+# =========================================================
+# ASR optional tuning / ASR 可选调优
+# =========================================================
 
-# [ZH] 显式覆盖作者卡目录路由，使用 "|" 分隔层级。默认值：空。
-# [EN] Explicit author-card route override, using "|" as separator. Default: empty.
-# [ZH] zh 默认：内容系统|对标研究|作者卡
-# [EN] zh preset default: 内容系统|对标研究|作者卡
-# [EN] en preset default: content-system|benchmark-research|author-cards
-# TIKOMNI_CARD_ROUTE_AUTHOR="content-system|benchmark|author-cards"
+# [ZH] U2 轮询超过多少秒仍为 pending 时，强制走 U3 fallback。默认值：60
+# [EN] Force U3 fallback if U2 is still pending after this many seconds. Default: 60
+TIKOMNI_U2_PENDING_TIMEOUT_SEC="60"
 
-# [ZH] 显式覆盖作者样本卡目录路由，使用 "|" 分隔层级。默认值：空。
-# [EN] Explicit author-sample-card route override, using "|" as separator. Default: empty.
-# [ZH] zh 默认：内容系统|对标研究|作者样本卡|{platform}-{author_slug}
-# [EN] zh preset default: 内容系统|对标研究|作者样本卡|{platform}-{author_slug}
-# [EN] en preset default: content-system|benchmark-research|author-sample-cards|{platform}-{author_slug}
-# TIKOMNI_CARD_ROUTE_AUTHOR_SAMPLE_WORK="content-system|benchmark|author-sample-cards|{platform}-{author_slug}"
+# [ZH] U2 轮询间隔，单位秒。默认值：3
+# [EN] U2 polling interval in seconds. Default: 3
+TIKOMNI_POLL_INTERVAL_SEC="3"
+
+
+# =========================================================
+# Advanced optional config / 高级可选配置
+# =========================================================
+
+# [ZH] 显式覆盖鉴权环境变量名。默认值：TIKOMNI_API_KEY
+# [EN] Override the auth environment variable name. Default: TIKOMNI_API_KEY
+# TIKOMNI_AUTH_ENV_KEY="TIKOMNI_API_KEY"
 
 
 # =========================================================
@@ -141,20 +139,3 @@ TIKOMNI_FILENAME_PATTERN_JSON="{timestamp}-{platform}-{identifier}{ext}"
 # [ZH] 若留空，则每个 skill 自动使用自己的 references/config-templates/defaults.yaml
 # [EN] If empty, each skill automatically uses its own references/config-templates/defaults.yaml
 # TIKOMNI_CONFIG_FILE=""
-
-
-# =========================================================
-# Creator-analysis only / 仅 creator-analysis 使用
-# =========================================================
-
-# [ZH] 作者级 LLM 分析超时，单位秒。默认值：45
-# [EN] Timeout for creator-level LLM analysis in seconds. Default: 45
-TIKOMNI_AUTHOR_ANALYSIS_TIMEOUT_SEC="45"
-
-# [ZH] sampled works 少于该阈值时跳过作者级 LLM 分析。默认值：5
-# [EN] Skip creator-level LLM analysis when sampled works are below this threshold. Default: 5
-TIKOMNI_AUTHOR_ANALYSIS_SMALL_SAMPLE_SKIP="5"
-
-# [ZH] sampled works 批量解释阶段超时，单位秒。默认值：45
-# [EN] Timeout for sampled-work batch explanation stage in seconds. Default: 45
-TIKOMNI_SAMPLED_EXPLANATION_TIMEOUT_SEC="45"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tikomni/skills",
-  "version": "0.1.2",
-  "description": "TikOmni skill installer CLI for Codex, Claude Code, and OpenClaw",
+  "version": "0.1.4",
+  "description": "TikOmni skill installer CLI for structured social media crawling in Codex, Claude Code, and OpenClaw",
   "license": "MIT",
   "homepage": "https://github.com/mark-ly-wang/TikOmni-Skills#readme",
   "bugs": {
@@ -13,7 +13,11 @@
   "files": [
     "bin/",
     "lib/",
-    "skills/",
+    "skills/social-media-crawl/**",
+    "!skills/social-media-crawl/**/__pycache__/**",
+    "!skills/social-media-crawl/**/*.py[cod]",
+    "!skills/social-media-crawl/**/.pytest_cache/**",
+    "!skills/social-media-crawl/scripts/pipelines/home_builders.py",
     ".skill-package-allowlist.txt",
     "env.example",
     "README.md",

package/skills/social-media-crawl/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: social-media-crawl
+description: Use this skill when the user asks about social media links, posts, creator homepages, comments, search results, rankings, livestreams, products, or wants to crawl / collect / fetch / retrieve / scrape social-media data; also trigger on 抓取 / 采集 / 获取 / 主页 / 评论 / 搜索 / 榜单 / 直播 / 商品 / 社交媒体.
+---
+
+# Social Media Crawl
+
+## When To Use
+
+- 当用户要处理社交媒体对象时使用，例如作品链接、作者主页、评论线程、搜索结果、榜单、直播间、商品页。
+- 当用户提到抓取、采集、获取、主页、评论、搜索、榜单、直播、商品、社交媒体等需求时使用。
+- 当输入是分享短链、作品 URL、主页 URL、平台 ID、关键词或页面入口时使用。
+
+## What To Help With
+
+- 识别平台和对象类型。
+- 优先处理单作品、作者主页和内容集合。
+- 获取事实字段、平台文案、字幕或转写文本。
+- 返回结构化 JSON，并在需要时写入事实卡。
+
+## Preferred Routing
+
+- 如果对象是以下 4 类，优先走固定 pipeline：
+  1. 抖音单作品
+  2. 小红书单作品
+  3. 抖音作者主页
+  4. 小红书作者主页
+- 其他对象优先走 MCP 工具链。
+
+## Working Style
+
+- 先看用户给的对象是什么，再选固定 pipeline 或 MCP 工具。
+- 优先返回事实字段，不补充主观分析。
+- 视频文本优先使用平台原生字幕；拿不到再走 ASR。
+- 默认输出以结构化 JSON 为主。
+
+## Workflow
+
+1. 识别平台和对象类型。
+2. 若命中固定 pipeline，直接运行固定脚本。
+3. 若未命中固定 pipeline，先调用 `tools/list`，再按 `catalog.search -> endpoint.describe -> api.call` 选择合适接口。
+4. 如果需要视频文本，执行 `u2.submit -> u2.query`；超过阈值仍未完成时走 U3 fallback。
+5. 整理为结构化结果。
+6. 若对象是作品，写入 `work_fact_card`。
+
+## References
+
+- MCP 使用契约：`references/mcp-usage-contract.md`
+- 输出 envelope：`references/contracts/output-envelope.md`
+- 作品事实卡字段：`references/contracts/work-fact-card-fields.md`
+- 泛对象 MCP 指引：`references/guides/generic-mcp-objects.md`
+- U2/U3 规则：`references/service-guides/u2-u3-mandatory-fallback.md`
+- 固定 pipeline 指南：`references/pipelines/`

package/skills/social-media-crawl/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Social Media Crawl"
+  short_description: "Structured social-media retrieval, transcription, and archival"
+  default_prompt: "Use $social-media-crawl to fetch, transcribe, normalize, and archive a concrete social-media object into structured JSON and work fact cards."
+

package/skills/social-media-crawl/references/contracts/output-envelope.md

@@ -0,0 +1,22 @@
+# Output Envelope
+
+## Required Fields
+
+- `object_type`
+- `platform`
+- `input`
+- `normalized`
+- `completeness`
+- `missing_fields`
+- `error_reason`
+- `extract_trace`
+- `request_id`
+
+## Semantics
+
+- `normalized` 只存结构化事实，不存分析推断。
+- `completeness` 允许值：`complete`、`partial`、`incomplete`。
+- `missing_fields` 是缺失字段列表。
+- `error_reason` 成功时可为空字符串或 `null`。
+- `extract_trace` 记录固定 pipeline 或 MCP 调度步骤。
+