# 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:
```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/`

