# Skill Lib ZeroClaw Migration Implementation Plan > **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. **Goal:** Create `/home/zyl/projects/sgClaw/skill_lib` as a dedicated skill library directory and restructure the current Zhihu browser capabilities into ZeroClaw-style skill packages. **Architecture:** Treat `skill_lib` as a standalone skill repository, not as an embedded Rust module tree. Use the ZeroClaw/open-skills layout `skill_lib/skills//SKILL.md`, keep each skill self-contained, and move long operational detail into `references/` plus any preserved source artifacts into `assets/`. Map the current four exposed Rust capabilities into three end-user skills: `zhihu-navigate`, `zhihu-write`, and `zhihu-hotlist`. **Tech Stack:** Markdown `SKILL.md`, YAML frontmatter, directory-based ZeroClaw skill packaging, existing SGClaw Zhihu Rust/JSON source material, shell validation commands. ### Task 1: Freeze The Target Layout **Files:** - Create: `/home/zyl/projects/sgClaw/skill_lib/` - Create: `/home/zyl/projects/sgClaw/skill_lib/README.md` - Create: `/home/zyl/projects/sgClaw/skill_lib/skills/` - Reference only: `/home/zyl/projects/sgClaw/claw/third_party/zeroclaw/src/skills/mod.rs` - Reference only: `/home/zyl/projects/sgClaw/claw/third_party/zeroclaw/skills/browser/SKILL.md` **Step 1: Create the top-level repository skeleton** Create: - `/home/zyl/projects/sgClaw/skill_lib/README.md` - `/home/zyl/projects/sgClaw/skill_lib/skills/` The README should state: - this directory is a dedicated ZeroClaw-style skill library - runtime skill packages live under `skills//` - each skill package uses `SKILL.md` plus optional `references/`, `scripts/`, and `assets/` **Step 2: Document the package contract in the README** Include: - required file: `SKILL.md` - supported frontmatter for this repo: `name`, `description`, `version`, `author`, `tags` - design rule: `description` must be trigger-oriented and not a workflow dump - design rule: keep `SKILL.md` concise and push long detail into `references/` **Step 3: Run structural sanity checks** Run: ```bash test -d /home/zyl/projects/sgClaw/skill_lib test -d /home/zyl/projects/sgClaw/skill_lib/skills test -f /home/zyl/projects/sgClaw/skill_lib/README.md ``` Expected: all commands exit `0`. ### Task 2: Define The Skill Inventory And Source Mapping **Files:** - Create: `/home/zyl/projects/sgClaw/skill_lib/skill_inventory.md` - Reference only: `/home/zyl/projects/sgClaw/claw/src/skill/mod.rs` - Reference only: `/home/zyl/projects/sgClaw/claw/src/skill/router.rs` - Reference only: `/home/zyl/projects/sgClaw/claw/src/skill/zhihu.rs` - Reference only: `/home/zyl/projects/sgClaw/claw/src/skill/zhihu_hotlist.rs` - Reference only: `/home/zyl/projects/sgClaw/claw/src/skill/zhihu_hotlist_store.rs` - Reference only: `/home/zyl/projects/sgClaw/claw/src/skill/zhihu_navigation.rs` - Reference only: `/home/zyl/projects/sgClaw/claw/resources/skills/zhihu_write_flow.json` - Reference only: `/home/zyl/projects/sgClaw/claw/resources/skills/zhihu_hotlist_flow.json` - Reference only: `/home/zyl/projects/sgClaw/claw/resources/skills/zhihu_navigation_pages.json` **Step 1: Write the migration inventory** Create `/home/zyl/projects/sgClaw/skill_lib/skill_inventory.md` with a three-row mapping: - `zhihu-navigate` ← current `zhihu_navigate` - `zhihu-write` ← current `zhihu_write` - `zhihu-hotlist` ← current `zhihu_hotlist_collect` + `zhihu_hotlist_report` **Step 2: Capture the non-migrated code responsibilities** Document explicitly that this migration does **not** port: - Rust router dispatch - browser pipe transport code - snapshot persistence implementation detail Document that the new repo is a skill library, not a Rust runtime. **Step 3: Record source artifacts per target skill** For each target skill, list: - source Rust module(s) - source JSON flow/catalog file(s) - important risk notes discovered during analysis **Step 4: Validate the inventory** Run: ```bash rg -n "zhihu-navigate|zhihu-write|zhihu-hotlist" /home/zyl/projects/sgClaw/skill_lib/skill_inventory.md ``` Expected: all three skill names appear exactly once as top-level migration targets. ### Task 3: Author The `zhihu-navigate` Skill Package **Files:** - Create: `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-navigate/SKILL.md` - Create: `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-navigate/references/routes-and-targets.md` - Create: `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-navigate/references/selector-strategy.md` - Create: `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-navigate/assets/zhihu_navigation_pages.source.json` - Reference only: `/home/zyl/projects/sgClaw/claw/src/skill/zhihu_navigation.rs` - Reference only: `/home/zyl/projects/sgClaw/claw/resources/skills/zhihu_navigation_pages.json` **Step 1: Preserve the raw source artifact** Copy the current navigation catalog into: - `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-navigate/assets/zhihu_navigation_pages.source.json` This file is for traceability only, not for frontmatter or prompt injection. **Step 2: Write the `SKILL.md`** Use ZeroClaw-style frontmatter: ```yaml --- name: zhihu-navigate description: Use when the user wants to open, switch, or navigate to a Zhihu page, tab, menu, profile area, notifications area, message area, or creator area through browser actions. version: 0.1.0 author: sgclaw tags: - zhihu - browser - navigation --- ``` The body should include: - overview - when to use - workflow for route vs component vs flow navigation - ambiguity handling rules - output contract - common mistakes **Step 3: Write `routes-and-targets.md`** Summarize: - route/component/flow/target model - representative target names - known alias conflicts - preferred disambiguation wording for future prompts **Step 4: Write `selector-strategy.md`** Document: - why selectors should prefer semantic hooks over CSS hash classes - fallback ordering - known brittle selectors from the current source **Step 5: Validate the package** Run: ```bash test -f /home/zyl/projects/sgClaw/skill_lib/skills/zhihu-navigate/SKILL.md test -f /home/zyl/projects/sgClaw/skill_lib/skills/zhihu-navigate/references/routes-and-targets.md test -f /home/zyl/projects/sgClaw/skill_lib/skills/zhihu-navigate/references/selector-strategy.md test -f /home/zyl/projects/sgClaw/skill_lib/skills/zhihu-navigate/assets/zhihu_navigation_pages.source.json ``` Expected: all commands exit `0`. ### Task 4: Author The `zhihu-write` Skill Package **Files:** - Create: `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-write/SKILL.md` - Create: `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-write/references/editor-flow.md` - Create: `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-write/references/publish-safety.md` - Create: `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-write/assets/zhihu_write_flow.source.json` - Reference only: `/home/zyl/projects/sgClaw/claw/src/skill/zhihu.rs` - Reference only: `/home/zyl/projects/sgClaw/claw/resources/skills/zhihu_write_flow.json` **Step 1: Preserve the raw source artifact** Copy: - `/home/zyl/projects/sgClaw/claw/resources/skills/zhihu_write_flow.json` to: - `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-write/assets/zhihu_write_flow.source.json` **Step 2: Write the `SKILL.md`** The frontmatter should name a single skill: - `name: zhihu-write` - description focused on when article drafting or publishing is requested The body should include: - prerequisites before touching the editor - workflow for draft-only vs publish - explicit confirmation gate before publish - required final report fields: title, mode, final URL if published, unresolved issues **Step 3: Write `editor-flow.md`** Document: - entry page - editor readiness checks - title/body fill rules - publish confirmation sequence - URL capture rules **Step 4: Write `publish-safety.md`** Document: - when to stop and ask for confirmation - what to do if title verification fails - what to do if the URL remains on edit mode - brittle selectors that must be revalidated first **Step 5: Validate the package** Run: ```bash test -f /home/zyl/projects/sgClaw/skill_lib/skills/zhihu-write/SKILL.md test -f /home/zyl/projects/sgClaw/skill_lib/skills/zhihu-write/references/editor-flow.md test -f /home/zyl/projects/sgClaw/skill_lib/skills/zhihu-write/references/publish-safety.md test -f /home/zyl/projects/sgClaw/skill_lib/skills/zhihu-write/assets/zhihu_write_flow.source.json ``` Expected: all commands exit `0`. ### Task 5: Author The `zhihu-hotlist` Skill Package **Files:** - Create: `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-hotlist/SKILL.md` - Create: `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-hotlist/references/collection-flow.md` - Create: `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-hotlist/references/report-format.md` - Create: `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-hotlist/references/data-quality.md` - Create: `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-hotlist/assets/zhihu_hotlist_flow.source.json` - Reference only: `/home/zyl/projects/sgClaw/claw/src/skill/zhihu_hotlist.rs` - Reference only: `/home/zyl/projects/sgClaw/claw/src/skill/zhihu_hotlist_store.rs` - Reference only: `/home/zyl/projects/sgClaw/claw/resources/skills/zhihu_hotlist_flow.json` **Step 1: Preserve the raw source artifact** Copy: - `/home/zyl/projects/sgClaw/claw/resources/skills/zhihu_hotlist_flow.json` to: - `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-hotlist/assets/zhihu_hotlist_flow.source.json` **Step 2: Write the `SKILL.md`** Use one skill to cover: - hotlist collection - comment metric collection - snapshot-style reporting The body should clearly separate: - collection workflow - report workflow - partial-failure handling - output contract **Step 3: Write `collection-flow.md`** Include: - hotlist page detection - hotlist HTML capture strategy - top N extraction - detail-page comment collection flow - metric parsing notes **Step 4: Write `report-format.md`** Define: - report header line - per-item summary line - field names and order - handling when comment metrics are missing **Step 5: Write `data-quality.md`** Document: - why partial success must be surfaced - what counts as incomplete data - known parser risks - recommended caution language in outputs **Step 6: Validate the package** Run: ```bash test -f /home/zyl/projects/sgClaw/skill_lib/skills/zhihu-hotlist/SKILL.md test -f /home/zyl/projects/sgClaw/skill_lib/skills/zhihu-hotlist/references/collection-flow.md test -f /home/zyl/projects/sgClaw/skill_lib/skills/zhihu-hotlist/references/report-format.md test -f /home/zyl/projects/sgClaw/skill_lib/skills/zhihu-hotlist/references/data-quality.md test -f /home/zyl/projects/sgClaw/skill_lib/skills/zhihu-hotlist/assets/zhihu_hotlist_flow.source.json ``` Expected: all commands exit `0`. ### Task 6: Normalize Frontmatter And Trigger Quality **Files:** - Modify: `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-navigate/SKILL.md` - Modify: `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-write/SKILL.md` - Modify: `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-hotlist/SKILL.md` **Step 1: Normalize frontmatter keys** Ensure each `SKILL.md` contains exactly these frontmatter keys in this order: - `name` - `description` - `version` - `author` - `tags` Do not add Rust-only or unofficial parser fields as required metadata. **Step 2: Check naming rules** Ensure skill names are: - lowercase - hyphenated - stable Names to keep: - `zhihu-navigate` - `zhihu-write` - `zhihu-hotlist` **Step 3: Tighten descriptions** Each description must: - begin with `Use when` - describe triggering conditions - mention Zhihu/browser context - avoid dumping full workflow detail **Step 4: Validate frontmatter** Run: ```bash rg -n "^name: |^description: |^version: |^author: |^tags:" /home/zyl/projects/sgClaw/skill_lib/skills/*/SKILL.md ``` Expected: every skill emits the same five key families. ### Task 7: Add Repository-Level Verification Notes **Files:** - Create: `/home/zyl/projects/sgClaw/skill_lib/VERIFY.md` - Modify: `/home/zyl/projects/sgClaw/skill_lib/README.md` **Step 1: Create `VERIFY.md`** Document the manual verification checklist: - all skill packages are under `skill_lib/skills/` - each package has `SKILL.md` - long details live in `references/` - preserved source JSON is in `assets/` - no Rust source is copied into the skill repo **Step 2: Link verification from the README** Add a short section in `README.md` pointing to `VERIFY.md`. **Step 3: Run repository-level checks** Run: ```bash find /home/zyl/projects/sgClaw/skill_lib/skills -mindepth 2 -maxdepth 2 -name SKILL.md | sort find /home/zyl/projects/sgClaw/skill_lib/skills -type d \( -name references -o -name assets \) | sort ``` Expected: - exactly three `SKILL.md` files - each skill has `references/` - each skill has `assets/` ### Task 8: Final Review Before Claiming Completion **Files:** - Review only: `/home/zyl/projects/sgClaw/skill_lib/` - Review only: `/home/zyl/projects/sgClaw/claw/docs/plans/2026-03-27-skill-lib-zeroclaw-plan.md` **Step 1: Review against ZeroClaw runtime constraints** Check that the final library respects the currently observed runtime facts: - directory-based skills - `SKILL.md` supported - simple frontmatter fields - optional `references/`, `scripts/`, `assets/` **Step 2: Review against authoring quality** Check that each skill: - is self-contained - has a narrow trigger boundary - avoids copying Rust internals into the prompt body - surfaces ambiguity and failure modes **Step 3: Produce the implementation report** The completion report must include: - created directories - created skill packages - any deliberate deviations from upstream ZeroClaw examples - verification commands actually run - unresolved risks **Step 4: Stop before unrelated expansion** Do not add: - extra skills beyond the three mapped ones - generic utility libraries - unrelated automation scripts - runtime code changes in `/home/zyl/projects/sgClaw/claw/src/skill/`