@tikomni/skills 0.1.0 → 0.1.2

package/README.md

@@ -88,22 +88,56 @@ They matter, but they do not define the full capability boundary of this reposit
 
 ### 2. Install skills
 
-If the npm package has been published, you can install directly with:
+Install directly from npm.
+
+First, list the currently available skills:
 
 ```bash
 npx @tikomni/skills list
+```
+
+Install into Codex:
+
+```bash
+# Install all skills
 npx @tikomni/skills install codex all
+
+# Install one specific skill
+npx @tikomni/skills install codex single-work-analysis
+```
+
+Default target: `$CODEX_HOME/skills`, default `~/.codex/skills`
+
+Install into Claude Code:
+
+```bash
+# Install all skills
+npx @tikomni/skills install claude-code all
+
+# Install only the creator-analysis skill
 npx @tikomni/skills install claude-code creator-analysis
+```
+
+Default target: `~/.claude/skills`
+
+Install into OpenClaw:
+
+```bash
+# Install all skills
+npx @tikomni/skills install openclaw all
+
+# Install into a custom directory
 npx @tikomni/skills install openclaw meta-capability --dir "/custom/skills"
 ```
 
-Default install targets:
+Default target: prefers `~/.openclaw/workspace/skills`, otherwise `~/.openclaw/skills`
+
+Common flags:
 
-- `codex` -> `$CODEX_HOME/skills`, default `~/.codex/skills`
-- `claude-code` -> `~/.claude/skills`
-- `openclaw` -> prefers `~/.openclaw/workspace/skills`, otherwise `~/.openclaw/skills`
+- `--dir <path>`: override the target `skills` directory
+- `--force`: overwrite an existing installed skill directory
 
-If you are not distributing through npm yet, you can also copy the target skill folder into the runtime's `skills` directory manually.
+If you do not want to use npm, you can also copy the target skill folder into the runtime's `skills` directory manually.
 
 ### 3. Configure environment variables
 

package/README.zh-CN.md

@@ -88,22 +88,56 @@
 
 ### 2. 安装 Skills
 
-如果 npm 包已发布，可以直接使用：
+使用 npm 直接安装。
+
+先查看当前可安装的 Skills：
 
 ```bash
 npx @tikomni/skills list
+```
+
+安装到 Codex：
+
+```bash
+# 安装全部 Skills
 npx @tikomni/skills install codex all
+
+# 只安装一个 Skill
+npx @tikomni/skills install codex single-work-analysis
+```
+
+默认目录：`$CODEX_HOME/skills`，默认值 `~/.codex/skills`
+
+安装到 Claude Code：
+
+```bash
+# 安装全部 Skills
+npx @tikomni/skills install claude-code all
+
+# 只安装创作者分析 Skill
 npx @tikomni/skills install claude-code creator-analysis
+```
+
+默认目录：`~/.claude/skills`
+
+安装到 OpenClaw：
+
+```bash
+# 安装全部 Skills
+npx @tikomni/skills install openclaw all
+
+# 安装到自定义目录
 npx @tikomni/skills install openclaw meta-capability --dir "/custom/skills"
 ```
 
-默认安装目录：
+默认目录：优先 `~/.openclaw/workspace/skills`，否则 `~/.openclaw/skills`
+
+常用参数：
 
-- `codex` -> `$CODEX_HOME/skills`，默认 `~/.codex/skills`
-- `claude-code` -> `~/.claude/skills`
-- `openclaw` -> 优先 `~/.openclaw/workspace/skills`，否则 `~/.openclaw/skills`
+- `--dir <path>`：显式指定目标 `skills` 目录
+- `--force`：覆盖已存在的同名 Skill 目录
 
-如果你暂时不走 npm 分发，也可以手动把目标 Skill 目录复制到对应运行时的 `skills` 目录。
+如果你不想使用 npm，也可以手动把目标 Skill 目录复制到对应运行时的 `skills` 目录。
 
 ### 3. 配置环境变量
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tikomni/skills",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "TikOmni skill installer CLI for Codex, Claude Code, and OpenClaw",
   "license": "MIT",
   "homepage": "https://github.com/mark-ly-wang/TikOmni-Skills#readme",

package/skills/creator-analysis/SKILL.md

@@ -8,7 +8,7 @@ description: Use this skill for creator, account profile, and content-collection
 ## When To Use
 
 - Use this skill when the target is a creator, account, profile page, channel, or content collection rather than a single content item.
-- Use this skill when the user wants a creator card, a full set of work cards, sampled explanations, or aggregated creator-level conclusions.
+- Use this skill when the user wants a creator card, author sample cards, sampled explanations, or aggregated creator-level conclusions.
 - Use this skill when multiple videos under one profile should go through batch ASR first.
 - Use this skill when the user provides a profile URL, creator handle, account identifier, channel entry, or another creator-level entry point.
 
@@ -16,12 +16,12 @@ description: Use this skill for creator, account profile, and content-collection
 
 - Fetch and normalize creator-side fact fields.
 - Fetch and normalize the full content collection under a profile.
-- Produce work fact cards for the retrieved items.
+- Produce author sample cards for the retrieved items.
 - Run batch ASR for video items when needed.
 - Complete bucketing, sampling, sampled explanations, and creator-level analysis.
-- Return creator cards, work cards, and aggregated conclusions.
+- Return creator cards, author sample cards, sampled enhanced cards, and aggregated conclusions.
 
-## Core Rules
+## Core Workflow Rules
 
 - Keep the task scoped to a creator, account profile, or content collection.
 - Prefer the platform guide first. Only go back to API discovery references when the guide is insufficient.
@@ -31,26 +31,50 @@ description: Use this skill for creator, account profile, and content-collection
 - Treat `author_analysis_v2` as the formal creator-level analysis object.
 - If `analysis_eligibility=incomplete`, keep the fact card but exclude the item from sampling, sampled explanations, and creator-level analysis.
 
+## Shared Layer Boundaries
+
+- Shared layer owns orchestration order, status semantics, output contracts, sampled-work explanation constraints, and final card-writing rules.
+- Platform layer owns route strategy, collector behavior, platform-field compatibility, adapter normalization, and platform-specific cleaning rules.
+- Keep sampled explanations as a batch-stage artifact. Do not reintroduce per-work deep analysis in the creator path.
+- Treat `author`, `author_sample_work`, and sampled enhanced cards as separate output roles with explicit routing semantics.
+
+## Platform Navigation
+
+- Start with the platform guide:
+  - Douyin: `references/platform-guides/douyin.md`
+  - Xiaohongshu: `references/platform-guides/xiaohongshu.md`
+  - Other platforms: `references/platform-guides/generic.md`
+- Route strategy, collector behavior, and raw payload retrieval:
+  - First stop: `scripts/author_home/collectors/homepage_collectors.py`
+- Platform-field compatibility and normalization:
+  - First stop: `scripts/author_home/adapters/platform_adapters.py`
+- Orchestration order, stage status, degradation, persistence, and final result assembly:
+  - First stop: `scripts/author_home/orchestrator/run_author_analysis.py`
+- Work-analysis artifacts, cache behavior, and structural labels:
+  - First stop: `scripts/author_home/orchestrator/work_analysis_artifacts.py`
+- Sampled explanations and creator-level analysis logic:
+  - First stop: `scripts/author_home/analyzers/`
+- Card writing and markdown rendering:
+  - First stop: `scripts/writers/write_author_homepage_samples.py`
+  - Supporting renderer: `scripts/writers/write_benchmark_card.py`
+
 ## Do Not
 
 - Do not paste sampled explanations directly into every work-card body.
 - Do not expose platform process fields directly in the final card body.
 - Do not introduce per-work LLM explanations inside the creator path.
-- Do not collapse a creator task into single-item analysis when the user clearly wants creator-level output.
+- Do not bypass the platform guide and jump straight into local helpers without understanding the route and contract expectations first.
 
 ## Workflow
 
 1. Identify the platform and confirm that the target is a creator, account profile, channel, or content collection.
 2. Read `references/contracts/creator-card-fields.md` to confirm required creator-card fields.
 3. Read `references/contracts/work-card-fields.md` to confirm required work-card fields for the collected items.
-4. Read the platform guide first:
-   - Douyin: `references/platform-guides/douyin.md`
-   - Xiaohongshu: `references/platform-guides/xiaohongshu.md`
-   - Other platforms: `references/platform-guides/generic.md`
+4. Read the platform guide first and then the first-stop implementation file for the problem type you are solving.
 5. If video items are involved, read `references/service-guides/asr-u2-u3-fallback.md` and then `references/asr-orchestration.md` to run batch ASR and fallback.
 6. Read `references/api-capability-index.md`, `references/api-tags/`, and `references/api-contracts/` only when the platform guide does not provide enough route or field detail.
 7. Read `references/workflow.md` to complete bucketing, sampling, sampled explanations, and `author_analysis_v2`.
-8. Return the creator card, work cards, and aggregated conclusions.
+8. Return the creator card, author sample cards, sampled enhanced cards, and aggregated conclusions.
 
 ## References
 

package/skills/creator-analysis/references/contracts/creator-card-fields.md

@@ -20,4 +20,6 @@
 
 - The creator card is the fact container for creator-level data.
 - The creator-level analysis body comes from `author_analysis_v2`, not from platform process fields.
+- The creator-card body should present the `author_analysis_v2` modules and representative works, not a raw JSON dump.
+- Debug JSON, validation, and trace data belong in appendix/details blocks rather than the main body.
 - Platform-native IDs stay in the internal reference layer and should not appear in the final creator-card body.

package/skills/creator-analysis/references/contracts/work-card-fields.md

@@ -1,4 +1,11 @@
-# Creator Work Card Fields
+# Creator Analysis Work Card Fields
+
+## Card Roles
+
+- `author_sample_card`
+  - Fact-and-structure card for every retrieved work in creator analysis.
+- `sample_work_card`
+  - Sampled-only enhanced card that reuses the same fact-and-structure fields and adds the explanation block.
 
 ## Fixed Display Fields
 
@@ -20,13 +27,42 @@
 - `share_url`
 - `primary_text`
 
-## Video-Only Additional Fields
+## Structural Display Fields
+
+- `performance_score`
+- `performance_score_norm`
+- `bucket`
+- `hook_type`
+- `structure_type`
+- `cta_type`
+- `content_form`
+- `style_markers`
+- `tags`
+
+## Shared Appendix Fields
+
+- `analysis_eligibility`
+- `analysis_exclusion_reason`
+
+## Video-Only Appendix Fields
 
 - `asr_raw`
 - `video_download_url`
 
+## Sampled-Only Explanation Block
+
+- `sampled_explanation.why_it_worked_or_failed`
+- `sampled_explanation.copyable_elements`
+- `sampled_explanation.non_copyable_elements`
+- `sampled_explanation.emotional_triggers`
+- `sampled_explanation.cognitive_gap`
+- `sampled_explanation.commercial_signal`
+
 ## Key Rules
 
-- Keep fact cards for all retrieved works.
-- The final work card should not expose `content_type`, `publish_time`, `create_time_sec`, `subtitle_raw`, `asr_source`, `asr_status`, or `asr_error_reason`.
+- Keep author sample cards for all retrieved works.
+- Only sampled works receive the sampled explanation block.
+- The final card should not expose `content_type`, `publish_time`, `create_time_sec`, `subtitle_raw`, `asr_source`, `asr_status`, or `asr_error_reason`.
+- Use `primary_text` as the main reading body and keep `asr_raw` in appendix/details only.
 - If a video item cannot obtain `asr_raw`, keep the fact card but mark `analysis_eligibility=incomplete` and exclude that item from creator analysis.
+- Do not introduce per-work standalone LLM analysis in creator analysis.

package/skills/creator-analysis/references/platform-guides/douyin.md

@@ -1,49 +1,54 @@
 # Douyin Creator Guide
 
-## Read This First
+## Use This Guide For
 
 - Use this guide first for Douyin creator, profile, and account tasks.
-- The validated chain in this repository is profile input -> `sec_user_id` resolution -> creator profile -> paginated post list.
-
-## Preferred Creator Resources
-
-- nickname: `nickname`
-- handle: `short_id` / `unique_id`
-- IP location
-- avatar
-- fan count, liked count, work count
-
-## Preferred Work Resources
-
-- work ID: `aweme_id`
-- title / caption: `title` / `desc`
-- video download URL: prefer the no-watermark path
-- engagement metrics: digg, comment, collect, share, play
-
-## Preferred Route Chain
-
-1. Profile identifier resolution: `GET /api/u1/v1/douyin/web/get_sec_user_id`
-   - OpenAPI-required input: `url`
-   - The current implementation also sends `share_url` redundantly.
-2. Creator profile: `GET /api/u1/v1/douyin/app/v3/handler_user_profile`
-   - Required input: `sec_user_id`
-3. Paginated post list: `GET /api/u1/v1/douyin/app/v3/fetch_user_post_videos`
-   - Required input: `sec_user_id`
-   - Common pagination parameters: `max_cursor`, `count`, `sort_type`
-
-## Unified Fields To Fill
-
-- creator card: `platform_author_id`, `author_handle`, `nickname`, `ip_location`, `signature`, `avatar_url`, `fans_count`, `liked_count`, `works_count`, `verified`
-- work cards: `platform_work_id`, `title`, `caption_raw`, `published_date`, `digg_count`, `comment_count`, `collect_count`, `share_count`, `play_count`, `video_download_url`
+- The validated creator chain in this repository is profile input -> `sec_user_id` resolution -> creator profile -> paginated post list.
+
+## Validated Route Chain
+
+1. Resolve `sec_user_id`: `GET /api/u1/v1/douyin/web/get_sec_user_id`
+2. Fetch creator profile: `GET /api/u1/v1/douyin/app/v3/handler_user_profile`
+3. Fetch paginated post list: `GET /api/u1/v1/douyin/app/v3/fetch_user_post_videos`
+
+## Required Unified Fields
+
+- creator side:
+  - `platform_author_id`
+  - `author_handle`
+  - `nickname`
+  - `ip_location`
+  - `signature`
+  - `avatar_url`
+  - `fans_count`
+  - `liked_count`
+  - `works_count`
+  - `verified`
+- work side:
+  - `platform_work_id`
+  - `title`
+  - `caption_raw`
+  - `published_date`
+  - `digg_count`
+  - `comment_count`
+  - `collect_count`
+  - `share_count`
+  - `play_count`
+  - `cover_image`
+  - `share_url`
+  - `source_url`
+  - `video_download_url`
 
 ## Route Rules
 
 - If `sec_user_id` is already available, skip the resolution route.
 - Default to the latest-post pagination path. Do not search random feed routes first.
+- The post-list route must supply stable `aweme_id`, publish time, and engagement fields before creator analysis can continue.
 - If batch U2 ASR is still incomplete after 120 seconds, follow `references/service-guides/asr-u2-u3-fallback.md` and use U3 fallback only for the unsuccessful subset.
 - If the profile chain still cannot supply key creator fields, go back to `references/api-capability-index.md` and the matching `references/api-tags/*.md` to find supplemental routes instead of giving up on the creator card.
 
-## Current Runnable Implementation
+## First Stops In Code
 
-- `skills/creator-analysis/scripts/author_home/adapters/platform_adapters.py`
-- `skills/creator-analysis/scripts/author_home/orchestrator/run_author_analysis.py`
+- Route and pagination behavior: `skills/creator-analysis/scripts/author_home/collectors/homepage_collectors.py`
+- Platform-field normalization: `skills/creator-analysis/scripts/author_home/adapters/platform_adapters.py`
+- Shared creator pipeline: `skills/creator-analysis/scripts/author_home/orchestrator/run_author_analysis.py`

package/skills/creator-analysis/references/platform-guides/generic.md

@@ -1,19 +1,20 @@
-# Generic Creator Guide
+# Generic Creator Adaptation Guide
 
 ## Goal
 
-Map an unfamiliar platform into the unified creator-card and work-card contracts and then complete the creator analysis flow.
+Map an unfamiliar platform into the creator-analysis contracts and only then feed it into the shared creator pipeline.
 
 ## Read Order
 
 - Start with `references/api-capability-index.md` to lock onto the relevant platform tag.
 - Read the matching `references/api-tags/<tag>.md` for route summaries, inputs, request bodies, and success-response summaries.
 - Prioritize routes related to `user / author / creator / profile / home / channel / posts / notes / videos`.
+- Then read `references/contracts/creator-card-fields.md`, `references/contracts/work-card-fields.md`, and `references/workflow.md`.
 - Add comment, media-download, subtitle, and extra-metric routes only when needed.
 
 ## Minimum Mapping Checklist
 
-creator side:
+- creator side:
 
 - `platform_author_id`
 - `author_handle`
@@ -27,7 +28,7 @@ creator side:
 - `works_count`
 - `verified`
 
-work side:
+- work side:
 
 - the required fields from the unified work-card field dictionary
 - for video items: `video_download_url`
@@ -38,9 +39,12 @@ work side:
 - If the platform provides multiple profile routes or posts routes, prefer the variant with fuller fields and more stable pagination.
 - The work-list route must reliably provide `platform_work_id` and the main published-time and engagement fields before sampling or aggregation can begin.
 - If video items have no subtitles and no download path, mark ASR as infeasible at the route-selection stage.
+- Do not invent platform cleaning rules inside the shared layer. Normalize in the platform adapter first.
+- If the platform still cannot satisfy the unified creator/work contracts, stop and report the mapping gap instead of pushing half-complete data into creator analysis.
 - If batch U2 ASR is still incomplete after 120 seconds, follow `references/service-guides/asr-u2-u3-fallback.md` and use U3 fallback only for the unsuccessful subset.
 
-## Current Runnable Implementation
+## First Stops For Adaptation
 
-- `skills/creator-analysis/scripts/author_home/`
-- `skills/creator-analysis/scripts/core/`
+- Collector and route selection: `skills/creator-analysis/scripts/author_home/collectors/homepage_collectors.py`
+- Platform normalization: `skills/creator-analysis/scripts/author_home/adapters/platform_adapters.py`
+- Shared creator orchestration: `skills/creator-analysis/scripts/author_home/orchestrator/run_author_analysis.py`

package/skills/creator-analysis/references/platform-guides/xiaohongshu.md

@@ -1,54 +1,69 @@
 # Xiaohongshu Creator Guide
 
-## Read This First
+## Use This Guide For
 
 - Use this guide first for Xiaohongshu creator, profile, and account tasks.
-- The validated chain in this repository is profile input -> `user_id` / `xsec_token` resolution -> profile cascade -> post-list cascade.
+- The validated creator chain in this repository is profile input -> `user_id` / `xsec_token` resolution -> profile cascade -> post-list cascade.
 
-## Preferred Creator Resources
+## Preferred Route Comparator
 
-- nickname
-- handle
-- IP location
-- avatar
-- fan count, liked count, work count
+- source priority: `app > web`
+- version priority within the same source: `v2 > v1`
+- desired order for the current creator-home pipeline: `app v2 -> app -> web v2`
 
-## Preferred Work Resources
+## Validated Route Chain
 
-- work ID: `note_id`
-- title / caption: `title` / `desc` / `content`
-- for video items, check native subtitles first
-- engagement metrics: digg, comment, collect, share, play
-
-## Preferred Route Chain
-
-1. Profile identifier resolution: `GET /api/u1/v1/xiaohongshu/app/get_user_id_and_xsec_token`
-   - OpenAPI-required input: `share_link`
-   - The current implementation also sends `share_url` and `url` redundantly.
+1. Resolve `user_id` / `xsec_token`: `GET /api/u1/v1/xiaohongshu/app/get_user_id_and_xsec_token`
 2. Profile cascade:
    - `GET /api/u1/v1/xiaohongshu/app_v2/get_user_info`
-   - `GET /api/u1/v1/xiaohongshu/web_v2/fetch_user_info_app`
    - `GET /api/u1/v1/xiaohongshu/app/get_user_info`
-   - Typical input: `user_id`, with `share_text` / `xsec_token` as needed
+   - `GET /api/u1/v1/xiaohongshu/web_v2/fetch_user_info_app`
 3. Post-list cascade:
    - `GET /api/u1/v1/xiaohongshu/app_v2/get_user_posted_notes`
-   - `GET /api/u1/v1/xiaohongshu/web_v2/fetch_home_notes_app`
    - `GET /api/u1/v1/xiaohongshu/app/get_user_notes`
-   - Typical input: `user_id`, `cursor`
+   - `GET /api/u1/v1/xiaohongshu/web_v2/fetch_home_notes_app`
 
-## Unified Fields To Fill
+## Required Unified Fields
 
-- creator card: `platform_author_id`, `author_handle`, `nickname`, `ip_location`, `signature`, `avatar_url`, `fans_count`, `liked_count`, `collected_count`, `works_count`, `verified`
-- work cards: `platform_work_id`, `title`, `caption_raw`, `published_date`, `digg_count`, `comment_count`, `collect_count`, `share_count`, `play_count`, `video_download_url`
+- creator side:
+  - `platform_author_id`
+  - `author_handle`
+  - `nickname`
+  - `ip_location`
+  - `signature`
+  - `avatar_url`
+  - `fans_count`
+  - `liked_count`
+  - `collected_count`
+  - `works_count`
+  - `verified`
+- work side:
+  - `platform_work_id`
+  - `title`
+  - `caption_raw`
+  - `published_date`
+  - `digg_count`
+  - `comment_count`
+  - `collect_count`
+  - `share_count`
+  - `play_count`
+  - `cover_image`
+  - `share_url`
+  - `source_url`
+  - `video_download_url`
 
 ## Route Rules
 
 - If `user_id` is already available, skip the resolution route. Treat `xsec_token` as supplemental rather than universally required.
-- Try both the profile cascade and the posts cascade in order, and switch to fallback based on field completeness.
+- Apply the comparator above consistently to both profile and post-list cascades.
+- Switch to fallback based on field completeness, not only on HTTP success.
+- For the current fixed pipeline, do not add a web-v1 fallback unless a later plan explicitly freezes its endpoint, parameters, and accept rules.
+- For video items, prefer native subtitles first; only move into batch ASR when native text is insufficient.
 - If batch U2 ASR is still incomplete after 120 seconds, follow `references/service-guides/asr-u2-u3-fallback.md` and use U3 fallback only for the unsuccessful subset.
 - If the profile-post chain still cannot provide stable fields, go back to `references/api-capability-index.md` and the matching `references/api-tags/*.md` for supplemental routes instead of sending half-complete data into creator analysis.
 
-## Current Runnable Implementation
+## First Stops In Code
 
-- `skills/creator-analysis/scripts/author_home/adapters/platform_adapters.py`
-- `skills/creator-analysis/scripts/author_home/orchestrator/run_author_analysis.py`
+- Route and pagination behavior: `skills/creator-analysis/scripts/author_home/collectors/homepage_collectors.py`
+- Platform-field normalization: `skills/creator-analysis/scripts/author_home/adapters/platform_adapters.py`
+- Shared creator pipeline: `skills/creator-analysis/scripts/author_home/orchestrator/run_author_analysis.py`