admin/claw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
claw/docs/plans/2026-03-27-skill-lib-zeroclaw-plan.md

412 lines
14 KiB
Markdown
Raw Permalink Blame History

# 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/`
Reference in New Issue View Git Blame Copy Permalink