skill-guide 0.2.1 → 0.3.1

package/CHANGELOG.md

@@ -5,6 +5,32 @@ All notable changes to skill-guide will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.1] - 2026-06-01
+
+### Added
+- Local health dashboard with radar chart, token estimate, review prompts, share page, and directory-based recommendations.
+- Packaging regression test that installs the generated npm tarball and starts the installed CLI.
+- Skill-definition regression test that keeps the agent entrypoint concise and trigger-first.
+
+### Changed
+- Health output now describes local metadata heuristics instead of unsupported community percentile comparisons.
+- Recommendation and cleanup wording now requires manual review before installing, editing, or deleting skills.
+- `SKILL.md` is now a thin CLI wrapper with English and Chinese dashboard support.
+- Online directory fetching now invokes `curl` directly without an unnecessary shell wrapper.
+
+### Fixed
+- Added `skill-registry.js` to the npm package so installed `0.3.x` CLI commands can start.
+
+### Removed
+- Tracked local agent settings and browser debug artifacts.
+
+## [0.3.0] - 2026-05-28
+
+Repository-only development version. It was not published to npm.
+
+### Added
+- Initial health dashboard, recommendation registry, share page, and personal profile experiments.
+
 ## [0.2.1] - 2026-05-17
 
 ### Fixed
@@ -19,8 +45,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `--doctor` diagnostics for Node.js, Codex home, skill counts, and source breakdown.
 - `--format json` for raw scanner output from the main CLI.
 - `--lang zh` built-in Chinese UI labels with `LABELS.zh` map.
-- Agent-side full translation for any language (ja, ko, fr, de, es, etc.) — SKILL.md workflow step 6.
-- Language auto-detection from user input (Chinese, Japanese, Korean, and others).
+- Built-in English and Chinese dashboard labels.
 - Markdown rendering in HTML output with smart truncation for long sections.
 - `data-i18n` attributes on all translatable HTML elements.
 - GitHub Actions test and Pages workflows.
@@ -35,7 +60,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 - `SKILL.md` now delegates HTML generation to the deterministic CLI, with the old scanner-driven instructions as fallback.
 - Cache files are now scoped to the active scan roots, avoiding stale results when switching between Claude Code and Codex environments.
-- Translation generalized from Chinese-only to any language — agent translates both `data-i18n` content and plain text.
+- Chinese dashboard labels can be selected with `--lang zh`.
 
 ## [0.1.0] - 2026-05-15
 

package/README.md

@@ -4,15 +4,18 @@
   <img src="https://img.shields.io/badge/Platform-Claude%20Code%20%7C%20Codex%20%7C%20cc--switch-818cf8?style=flat-square" />
   <img src="https://img.shields.io/github/actions/workflow/status/gtskevin/skill-guide/test.yml?branch=main&style=flat-square&label=tests" />
   <img src="https://img.shields.io/badge/License-MIT-green?style=flat-square" />
-  <img src="https://img.shields.io/badge/Language-Any%20%F0%9F%8C%90-7dd3fc?style=flat-square" />
+  <img src="https://img.shields.io/badge/Language-English%20%7C%20Chinese-7dd3fc?style=flat-square" />
+  <img src="https://img.shields.io/badge/Feature-Health%20Dashboard-fbbf24?style=flat-square" />
 </p>
 
 <p align="center">
   <img src="demo.gif" alt="skill-guide demo — npx skill-guide --open generates HTML slides" width="760" />
 </p>
 
-> **200+ agent skills installed but you only use 3?**
-> One command scans everything — Claude Code, Codex, cc-switch, plugins — and generates a beautiful slide deck so you actually know what you have.
+> **Installed so many agent skills that you cannot remember what you have?**
+> One command scans everything — Claude Code, Codex, cc-switch, plugins — and generates a beautiful dashboard so you actually know what you have.
+>
+> Shows your local skill profile, radar chart, token budget estimate, and review candidates — all in one click.
 
 <p align="center">
   <a href="https://gtskevin.github.io/skill-guide/"><strong>Live Demo</strong></a>
@@ -25,22 +28,29 @@
 </p>
 
 ```bash
-npx skill-guide --open        # ← that's it. HTML slides open in your browser.
+npx skill-guide               # ← that's it. Dashboard opens in your browser.
 ```
 
 ## What it does
 
-skill-guide reads every skill from Claude Code, Codex, `~/.cc-switch/skills/`, and plugin marketplaces, then generates a polished slide deck you can view in any browser.
+skill-guide reads every skill from Claude Code, Codex, `~/.cc-switch/skills/`, and plugin marketplaces, then generates a polished dashboard you can view in any browser.
 
-**4 modes:**
+**Platform-aware:** Automatically detects whether you're running inside Codex or Claude Code and shows only the relevant skills. Token budget is calculated per-platform, not across all platforms.
 
-| Mode | Command | Output |
-|------|---------|--------|
-| **Discovery** | `/skill-guide` or `npx skill-guide --open` | Stats, category map, highlights, quick reference |
-| **Deep-dive** | `/skill-guide investigate` or `npx skill-guide --skill investigate --open` | How it works, when to use, limitations, triggers |
-| **Tool-selection** | "Which skill for security?" | Ranked recommendations with comparison |
-| **Full manual** | `/skill-guide all` or `npx skill-guide --full --open` | One page per skill, complete reference |
-| **Doctor** | `npx skill-guide --doctor` | Environment and source diagnostics |
+**3 modes:**
+
+| Mode | Command | What it does |
+|------|---------|-------------|
+| **Dashboard** | `npx skill-guide` | Personality, radar, token budget, cleanup guide, highlights |
+| **Find** | `npx skill-guide --find <name\|query>` | Search by keyword or deep dive into a specific skill |
+| **Doctor** | `npx skill-guide --doctor` | Environment diagnostics (broken files, duplicates, paths) |
+
+**Flags:**
+- `--all` — Show skills from all platforms (default: current platform only)
+- `--full` — Expand dashboard to include all skill details
+- `--recommend` — Show recommendations from online directories
+- `--share` — Generate shareable portfolio page
+- `--no-open` — Do not open HTML in browser
 
 ## Platform Support
 
@@ -75,6 +85,36 @@ skill-guide reads every skill from Claude Code, Codex, `~/.cc-switch/skills/`, a
   </tr>
 </table>
 
+### Health Dashboard Preview
+
+```bash
+npx skill-guide
+```
+
+**Terminal output:**
+```
+🟡 Health Score: 68/100
+🏛️ Local profile: Collector (The Collector)
+The local scan found a large skill inventory. Review descriptions, sources, and actual needs periodically.
+
+📦 Total Skills: 338
+🔤 Description Token Estimate: ~20.0K (9.98% of a 200K reference context)
+📍 Local profile: based only on the current scan
+
+🛡️ Security Review [medium]
+   Review skills with security flags manually
+📦 Budget Overage [high]
+   Review longer descriptions when the local reference budget is exceeded
+
+Token Efficiency ████████░░ 80/100
+Organization ██████████ 100/100
+Security ████░░░░░░ 40/100
+Freshness ██████████ 100/100
+Budget Control ██░░░░░░░░ 21/100
+```
+
+Health scores are local heuristics for review. They do not measure community rank, actual usage frequency, or whether deleting a skill is safe.
+
 ## Quick Start
 
 **1. Try instantly** — no install needed:
@@ -89,9 +129,9 @@ npx skills add gtskevin/skill-guide
 
 **3. Use it** — type `/skill-guide` in Claude Code, or use the CLI:
 ```bash
-npx skill-guide --open                        # Discover all skills
-npx skill-guide --search security --open      # Find skills for a task
-npx skill-guide --skill tdd --open            # Deep-dive one skill
+npx skill-guide                               # See your dashboard
+npx skill-guide --find security               # Find skills for a task
+npx skill-guide --find tdd                    # Deep-dive one skill
 npx skill-guide --full --open                 # Generate a full manual
 npx skill-guide --doctor                      # Diagnose your setup
 ```
@@ -123,6 +163,10 @@ ln -s "$(pwd)/skill-guide" "${CODEX_HOME:-$HOME/.codex}/skills/skill-guide"
 npx skill-guide --open
 npx skill-guide --search security --open
 npx skill-guide --skill test-driven-development --open
+npx skill-guide --share --open                    # Share your skill stack
+npx skill-guide --recommend --open                # Review directory mentions and same-category candidates
+npx skill-guide                   # Health dashboard with personality & radar chart
+npx skill-guide --wrapped --open                  # Compatibility alias for the local profile
 npx skill-guide --format json
 npx skill-guide --doctor
 ```
@@ -152,16 +196,53 @@ Or: "帮我推荐一个做测试的技能"
 /skill-guide all
 ```
 
+### Share your skill stack
+```bash
+npx skill-guide --share --open                    # Generate portfolio page
+npx skill-guide --share --user @gtskevin --open   # With personalized tag
+```
+
+### Get recommendations
+```bash
+npx skill-guide --recommend --open                # HTML report
+npx skill-guide --recommend                       # Terminal output
+npx skill-guide --recommend --format json         # JSON for agents
+```
+
+### Health check your skills
+```bash
+npx skill-guide                   # Full HTML dashboard
+npx skill-guide --health                          # Terminal output
+npx skill-guide --health --lang zh --open         # Chinese UI
+```
+
+**What you get:**
+- **Health Score** — 0-100 rating of your skill library's health
+- **Personality Analysis** — Are you a Collector, Minimalist, Security Expert, or Specialist?
+- **Five-Dimension Radar Chart** — Token Efficiency, Organization, Security, Freshness, Budget Control
+- **Review Prompts** — Local candidates based on scanned skill metadata
+- **Token Estimate** — Approximate description cost before a conversation starts
+- **One-Click Share** — Copy report to clipboard for sharing
+
+### Personal Skill Report (--wrapped)
+
+Your local profile for AI skills:
+- Skill personality type (Collector, Minimalist, Security Expert, etc.)
+- Skill DNA breakdown (category distribution)
+- Readiness breakdown based on local metadata
+- Shareable HTML report with one-click copy
+
 ## How it works
 
 ```
 skill-guide/
-├── SKILL.md             # Skill definition + HTML generation rules
-├── agents/openai.yaml   # Codex/OpenAI skill UI metadata
+├── SKILL.md              # Natural-language CLI entrypoint
+├── agents/openai.yaml    # Codex/OpenAI skill UI metadata
 ├── skill-guide.js        # Deterministic CLI + HTML generator
-├── scan-skills.js       # Zero-dependency Node.js scanner
-├── demo.html            # Demo presentation (this is what you see above)
-└── LICENSE              # MIT
+├── scan-skills.js        # Zero-dependency Node.js scanner
+├── skill-registry.js     # Online directory fetching + recommendation engine
+├── demo.html             # Demo presentation (this is what you see above)
+└── LICENSE               # MIT
 ```
 
 1. `scan-skills.js` scans Claude Code, Codex, cc-switch, and plugin skill directories; parses YAML frontmatter; extracts sections and key paragraphs
@@ -189,7 +270,11 @@ skill-guide/
 | `--search <query>` | Generate recommendations for a task |
 | `--skill <name>` | Generate a deep-dive for one skill |
 | `--full` | Generate a complete manual |
-| `--lang <code>` | UI language (en, zh, or any — auto-translated) |
+| `--share` | Generate a shareable portfolio HTML |
+| `--user <name>` | Add personalized tag to share page |
+| `--recommend` | Show directory mentions and same-category review candidates |
+| `--health` | Generate health dashboard with local profile, radar chart, and review prompts |
+| `--lang <code>` | UI language (`en` or built-in `zh`) |
 | `--doctor` | Check paths, sources, and scan counts |
 
 ### Doctor checks
@@ -202,18 +287,19 @@ Skills are automatically sorted into 9 categories: `testing`, `design`, `securit
 
 ## Language Support
 
-Automatic — ask in any language, get output in that language. No configuration needed.
+Dashboard labels are available in English and Chinese. Agents can summarize results in the user's language without modifying the generated HTML.
 
 - **English** — default
 - **Chinese** — built-in (`--lang zh`)
-- **Japanese, Korean, French, German, Spanish, ...** — agent-side translation (works in Claude Code and Codex)
+- **Other languages** — agent summary in the user's language; dashboard labels remain English
 
 ## Why skill-guide?
 
-- **The only skill that maps your skills** — scans Claude Code, Codex, cc-switch, and plugin sources in one visual overview
+- **Cross-platform inventory** — scans Claude Code, Codex, cc-switch, and plugin sources in one visual overview
+- **Health dashboard** — local profile, radar chart, and review prompts for your skill library
 - **Zero dependencies** — pure Node.js with `fs`, `path`, `os`. No `npm install` needed
 - **Beautiful output** — scroll-snap slides with keyboard nav, animations, and responsive design
-- **Any language** — ask in Chinese, get Chinese. Ask in Japanese, get Japanese. Auto-detected.
+- **Bilingual dashboard** — English by default, with built-in Chinese labels via `--lang zh`
 - **Smart caching** — 5-minute TTL so repeated queries are instant
 - **5 seconds to "wow"** — `npx skill-guide --open` is all you need
 
@@ -223,11 +309,11 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 ## Roadmap
 
-- [ ] `--share` — generate a shareable standalone HTML or Markdown summary
+- [x] `--share` — generate a shareable standalone HTML or Markdown summary
+- [x] `--health` — health dashboard with local profile, radar chart, and review prompts
 - [ ] Gemini CLI skill scanning (`~/.gemini/skills`)
 - [ ] `--diff` — show recently added/removed skills since last scan
 - [ ] `--export markdown` — output a Markdown table for pasting into issues and docs
-- [ ] Skill health scores based on frontmatter completeness
 
 Have an idea? [Open a feature request](https://github.com/gtskevin/skill-guide/issues/new?template=feature_request.yml).
 

package/SKILL.md

@@ -1,266 +1,40 @@
 ---
 name: skill-guide
-description: |
-  Discover, understand, compare, and choose from installed Agent Skills across
-  Claude Code, Codex, local skill folders, and plugin marketplaces. Generates
-  HTML slide presentations with skill overviews, deep-dives, and tool
-  recommendations. Use when user says "skill-guide", asks what skills they
-  have, wants to explore Claude Code or Codex skills, asks "tell me about
-  a skill", "which skill for X", "help me understand my skills", or wants to
-  map installed agent capabilities.
+description: Use when the user wants to discover, inspect, compare, diagnose, or choose installed Agent Skills across Codex, Claude Code, cc-switch, or plugin directories.
 allowed-tools:
   - Bash
-  - Read
-  - Write
 ---
 
 # Skill Guide
 
-## 1. When to Use
+## Overview
 
-Activate this skill when the user wants to explore, discover, compare, or learn about their installed Agent Skills across Claude Code, Codex, local skill folders, and plugin marketplaces. The output is a polished HTML slide presentation opened in the browser.
+Use the bundled zero-dependency CLI to scan local skill metadata and generate a browser-ready HTML dashboard. Treat health scores and recommendations as local review prompts, not usage metrics or deletion decisions.
 
-**Trigger conditions:**
-- User types `/skill-guide` (bare or with arguments)
-- User asks "what skills do I have", "show me my skills", "what Codex skills do I have"
-- User asks about a specific skill: "tell me about frontend-slides"
-- User describes a task and wants to know which skill fits: "which skill for code review"
-- User says "help me understand my skills"
+## Workflow
 
-## 2. Mode Detection
+1. Infer the requested mode from the user's request.
+2. Run the matching command from this skill directory.
+3. Add `--lang zh` for a Chinese dashboard. English is the default.
+4. Add `--open` unless the user asks for terminal output or a file only.
+5. Summarize the generated result and report the output path when HTML is created.
 
-Determine the mode from user input:
+| User goal | Command |
+|---|---|
+| Dashboard | `node <skill-dir>/skill-guide.js` |
+| Find or inspect a skill | `node <skill-dir>/skill-guide.js --find "<query>"` |
+| Diagnose local setup | `node <skill-dir>/skill-guide.js --doctor` |
+| Review directory mentions | `node <skill-dir>/skill-guide.js --recommend` |
+| Generate a share page | `node <skill-dir>/skill-guide.js --share [--user <name>]` |
+| Generate a full manual | `node <skill-dir>/skill-guide.js --full` |
+| Return structured data | `node <skill-dir>/skill-guide.js --format json` |
 
-| User Input | Mode | Scanner Flag |
-|------------|------|-------------|
-| `/skill-guide` (bare, no args) | discovery | `--list` |
-| `/skill-guide <name>` or "tell me about <name>" | deep-dive | `--skill <name>` |
-| Task description or "which skill for X" | tool-selection | `--search <query>` |
-| `/skill-guide all` | full-manual | `--full` |
+Use `--refresh` when the user expects newly installed or removed skills to appear. Use `--all` only when the user wants a cross-platform inventory.
 
-**Resolution rules (apply in order):**
-1. If argument is "all" (case-insensitive) -> full-manual mode
-2. If argument exactly matches a known skill name -> deep-dive mode
-3. If argument contains verbs (e.g., "review", "build", "test") or question words ("which", "what", "how") -> tool-selection mode
-4. If bare `/skill-guide` with no argument -> discovery mode
+## Guardrails
 
-## 3. Workflow
-
-Follow these steps exactly:
-
-1. **Determine mode** from user input using the rules in section 2.
-2. **Detect language**: Determine the user's language from their input.
-   - Chinese: input contains Chinese characters → lang = `zh`
-   - Japanese: input contains Japanese characters (`/[あ-んア-ンヶッ]/` or hiragana/katakana) → lang = `ja`
-   - Korean: input contains Hangul (`/[가-힣]/`) → lang = `ko`
-   - Any other non-English language: if the user writes in a language other than English, detect it and set lang accordingly (e.g., `fr`, `de`, `es`, `pt`, `ru`, etc.)
-   - English or cannot determine: lang = `en` (default, no translation needed)
-3. **Run the deterministic CLI**: `node <skill-dir>/skill-guide.js <flag> [args] [--lang <lang>]`, where `<skill-dir>` is the directory containing this SKILL.md file.
-   - If lang is `en`, add `--open` to the CLI command (open directly, no translation needed).
-   - If lang is NOT `en`, do NOT add `--open` (translation happens before opening).
-4. Map modes to CLI flags:
-   - Discovery: `node <skill-dir>/skill-guide.js`
-   - Deep-dive: `node <skill-dir>/skill-guide.js --skill <name>`
-   - Tool-selection: `node <skill-dir>/skill-guide.js --search "<query>"`
-   - Full manual: `node <skill-dir>/skill-guide.js --full`
-   - Diagnostics: `node <skill-dir>/skill-guide.js --doctor`
-   Append `--lang <lang>` to any command when a non-English language is detected.
-5. If `skill-guide.js` is unavailable, fall back to running `scan-skills.js` and generating HTML using the rules below.
-6. **Post-translate for non-English languages** (when lang is NOT `en`):
-   After the CLI generates the HTML file, perform a full translation pass:
-   a. Read the generated HTML file.
-   b. Translate ALL English text content inside elements with `data-i18n` attributes, AND all UI label text (headings, kicker, subtitle, section headers like "运作原理", "何时使用", etc.) to the user's detected language.
-      - The `data-i18n` attributes mark translatable content: `desc` (descriptions), `section-title` (step/section titles), `section-body` (step/section content), `how-it-works`, `when-to-use`, `limitations`.
-      - Also translate any other visible text: cover titles, category names, stats labels, navigation text, and any Chinese/English UI labels already in the HTML.
-      - Preserve ALL HTML tags, CSS classes, JavaScript, attribute names, and document structure exactly as-is.
-      - Only translate the **text content** between tags — never modify tag names, attributes, CSS, or JavaScript.
-      - Do NOT translate: content inside `<code>` tags, skill names, tool names, CSS property values, JavaScript code.
-      - Translate naturally as a fluent native speaker would write it — not word-by-word. Adapt sentence structure for natural readability in the target language.
-      - Keep markdown-derived formatting: `<strong>` stays `<strong>`, `<code>` stays `<code>`, `<blockquote>` stays `<blockquote>`.
-   c. Write the translated HTML back to the same file path using the Write tool.
-   d. Open the file in the browser: `open <filepath>` (macOS) or equivalent.
-   e. Report completion to the user with a brief summary in their language.
-7. **English mode**: When lang is `en`, add `--open` to the CLI command directly and skip step 6.
-
-## 4. HTML Generation Rules
-
-### Technical Requirements
-
-- Single-file HTML with all CSS and JS inlined. Zero external dependencies.
-- Full-screen scroll-snap slides:
-  ```css
-  .slide {
-    height: 100vh;
-    height: 100dvh;
-    overflow: hidden;
-    scroll-snap-align: start;
-  }
-  ```
-- CSS custom properties with `clamp()` for responsive sizing.
-- Keyboard navigation (arrow keys), scroll wheel, and touch swipe.
-- IntersectionObserver for entrance animations: elements with class `.rv` get class `.v` added when visible.
-- Navigation dots on the right side.
-- Progress bar at the top.
-- Page number: bottom-right corner as `<div class="sn-txt">N/total</div>`.
-- `@media (prefers-reduced-motion: reduce)` disables animations.
-- Every slide MUST fit within the viewport. If content overflows, split into multiple slides.
-
-### Color Theme CSS Variables
-
-```css
-:root {
-  --bg: #eef2ff;
-  --card: #fff;
-  --cs: 0 4px 20px rgba(100,100,180,0.07);
-  --t: #1e293b;
-  --ts2: #64748b;
-  --ab: #818cf8;
-  --ap: #f0abfc;
-  --am: #6ee7b7;
-  --ao: #fdba74;
-  --ay: #fde047;
-  --al: #c4b5fd;
-  --ar: #fda4af;
-  --as: #7dd3fc;
-  --r: clamp(10px,1.8vw,18px);
-}
-```
-
-Each slide gets a subtle gradient background and decorative blurred circles (pseudo-elements with `filter: blur(80px)`, low opacity, positioned absolutely) for atmosphere.
-
-### Per-Mode Page Structure
-
-#### Discovery Mode (4 pages)
-
-**Page 1 - Cover:**
-- Title: If scanner sources include both Claude and Codex, use "Your Agent Skills" (EN) or "你的 Agent Skills 技能库" (ZH). If only Claude sources are present, use "Your Claude Code Skills" / "你的 Claude Code 技能库". If only Codex sources are present, use "Your Codex Skills" / "你的 Codex 技能库".
-- Subtitle: total skill count + per-source breakdown (e.g., "12 Claude skills, 8 Codex skills, 20 plugin skills")
-- Decorative background with gradient and blurred circles
-
-**Page 2 - Category Map:**
-- Group skills by their `category` field
-- 3-column card grid
-- Each card shows: skill name, 1-line description, category badge (colored pill)
-- Use distinct accent colors per category for visual separation
-
-**Page 3 - Highlights:**
-- Top 5-8 most versatile skills (ranked by number of triggers or multiple sources)
-- Each highlight: skill name + full description + trigger words as small badges
-- Use a prominent card layout with the accent color
-
-**Page 4 - Quick Reference:**
-- Table with columns: Name | Description | Triggers | Category
-- Compact rows, alternating background for readability
-- Sticky header if content is long
-
-#### Deep-dive Mode (1-3 pages per skill)
-
-**Page 1 - Overview:**
-- Large skill name as title
-- Full description as subtitle
-- Category badge (colored pill)
-- Source badge (showing where the skill comes from)
-- List of `allowedTools` as code-styled tags
-
-**Page 2 - How It Works:**
-- Render `sections` array as a numbered step flow with circle numbers (1, 2, 3...)
-- If `howItWorks` field exists, render it as a detail/expandable box
-- Use connecting lines or arrows between steps for flow visualization
-
-**Page 3 - When to Use:**
-- `whenToUse` items as green "Use when..." tags
-- `limitations` items as orange "Caution" tags
-- `triggers` as keyword badges in a separate section
-- If Page 2 + Page 3 content combined is short enough for one slide, merge them
-
-#### Tool-selection Mode (2-3 pages)
-
-**Page 1 - Match Results:**
-- User's task description displayed as a quote/callout
-- Matched skills ranked by relevance (count of trigger matches + description keyword overlap)
-- Each match shows: name, relevance score, top matching triggers
-
-**Page 2 - Side-by-side Comparison:**
-- Top 2-3 matches in a comparison layout
-- Columns: Feature | Skill A | Skill B | Skill C
-- Rows: Description, Triggers, When to Use, Limitations, Tools
-
-**Page 3 - Workflow Suggestion:**
-- Flow diagram showing how skills can combine: Skill A -> Skill B -> Result
-- Use CSS-only arrows between skill boxes
-- Brief explanation of why this combination works
-
-#### Full Manual Mode
-
-**Page 1 - Cover:**
-- Title: "Complete Skill Manual" / "完整技能手册"
-- Total skill count + source breakdown
-
-**Page 2 - Category Index:**
-- Category names with skill count per category
-- Clickable/visual index layout
-
-**One page per skill (compact format):**
-- Skill name as heading
-- 2-line description
-- Trigger words as badges
-- When-to-use summary (1-2 lines)
-- Keep each skill to one page maximum
-
-**Last page - Quick Reference Table:**
-- Same as Discovery Page 4 but covering all skills
-
-**Overflow protection:** If total skills > 30, warn the user before generating: "This will produce N pages. Continue?" Then proceed only after confirmation.
-
-### Content Mapping from JSON
-
-Map scanner JSON fields to HTML content:
-
-| JSON Field | HTML Section |
-|-----------|-------------|
-| `name` + `description` | Slide title, subtitle, card header |
-| `howItWorks` | "How it works" detail box |
-| `sections` | Numbered step flow |
-| `whenToUse` + `triggers` | "When to use" tags + trigger keyword list |
-| `limitations` | "Limitations" caution area |
-| `allowedTools` | Tools list (collapsible, for advanced users) |
-| `category` | Category badge, used for grouping and coloring |
-| `source` | Source badge showing origin |
-
-### Language Handling
-
-The CLI uses `--lang zh` for Chinese labels as a built-in default. For any other language, the agent-side translation step (workflow step 6) handles ALL UI labels and content translation. The agent translates everything — both `data-i18n` marked content and any other visible text (headings, kicker, stats labels, etc.) — to the detected target language.
-
-The CLI's built-in Chinese label map is used as a starting point when `--lang zh` is passed. For all other languages, the CLI generates English labels and the agent translates them.
-
-| English Label | Chinese Label (built-in) |
-|--------------|---------------|
-| Your Agent Skills | 你的 Agent Skills 技能库 |
-| Your Claude Code Skills | 你的 Claude Code 技能库 |
-| Your Codex Skills | 你的 Codex 技能库 |
-| Category Map | 分类概览 |
-| Highlights | 精选推荐 |
-| Quick Reference | 快速参考 |
-| How It Works | 运作原理 |
-| When to Use | 何时使用 |
-| Limitations | 使用限制 |
-| Triggers | 触发词 |
-| Complete Skill Manual | 完整技能手册 |
-| Match Results | 匹配结果 |
-| Comparison | 对比分析 |
-| Workflow Suggestion | 工作流建议 |
-| Use when... | 适用场景... |
-| Caution | 注意 |
-| Tools | 工具列表 |
-| Source | 来源 |
-| Category | 分类 |
-
-For all other languages (Japanese, Korean, French, German, etc.), the agent translates these labels as part of step 6.
-
-## 5. Anti-Patterns
-
-- **Never fabricate skill descriptions.** Only use data returned by the scanner. If the scanner returns empty or fails, show an error slide instead of guessing.
-- **Never skip running the scanner.** The scanner is the sole source of truth for installed skills.
-- **Never generate more than 30 pages without asking.** Prompt the user first.
-- **Never include skills without a name.** Skip malformed entries and log a warning to console.
-- **Never hard-code skill lists.** Always derive from scanner output at generation time.
+- The scanner reads local metadata; it does not measure actual usage frequency.
+- Same-category suggestions and directory mentions require human review before installing, editing, or deleting anything.
+- Never delete skills, install packages, or publish results based only on a generated score.
+- Built-in dashboard labels support English and Chinese. For other languages, summarize the result in the user's language without rewriting generated HTML unless explicitly requested.
+- If the CLI is unavailable, report the missing file instead of silently replacing its behavior.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skill-guide",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Scan 6+ skill directories across Claude Code, Codex, and cc-switch, then generate beautiful HTML slide presentations.",
   "license": "MIT",
   "type": "commonjs",
@@ -14,6 +14,7 @@
     "SKILL.md",
     "skill-guide.js",
     "scan-skills.js",
+    "skill-registry.js",
     "demo.html",
     "demo.gif",
     "social-preview.png",
@@ -31,7 +32,7 @@
     "scan:full": "node scan-skills.js --full",
     "guide": "node skill-guide.js --open",
     "doctor": "node skill-guide.js --doctor",
-    "test": "node --check scan-skills.js && node --check skill-guide.js && node --test test/*.test.js && node scan-skills.js --list >/dev/null && node scan-skills.js --search security >/dev/null && node scan-skills.js --full >/dev/null"
+    "test": "node --check scan-skills.js && node --check skill-guide.js && node --check skill-registry.js && node --test test/*.test.js && node scan-skills.js --list >/dev/null && node scan-skills.js --search security >/dev/null && node scan-skills.js --full >/dev/null"
   },
   "engines": {
     "node": ">=18"