claw/docs/plans/2026-03-27-skill-lib-zeroclaw-plan.md

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-name>/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/<name>/
• 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:

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:

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:

---
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:

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:

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:

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:

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:

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/