skill-guide 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+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.2.0] - 2026-05-15
+
+### Added
+- Deterministic `skill-guide` CLI for direct `npx skill-guide --open` usage.
+- `--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).
+- 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.
+- Regenerated Agent Skills demo screenshots, demo GIF, and social preview image.
+- Codex skill discovery from `~/.codex/skills`, `$CODEX_HOME/skills`, and Codex plugin cache.
+- OpenAI/Codex UI metadata in `agents/openai.yaml`.
+- Cross-platform Agent Skills positioning and Codex install instructions.
+- Scanner tests for Codex sources and cache isolation.
+- Scanner tests for multiline descriptions, quoted values, lists, and duplicate source labels.
+- Translation tests: Chinese label rendering, English preservation, section/summary translation.
+
+### 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.
+
+## [0.1.0] - 2026-05-15
+
+### Added
+- `scan-skills.js` — zero-dependency Node.js scanner with 4 modes (`--list`, `--skill`, `--search`, `--full`)
+- `SKILL.md` — Claude Code skill definition with HTML generation rules for 4 interaction modes
+- Auto-categorization into 9 categories (testing, design, security, documentation, automation, deployment, code-quality, development, other)
+- Three-layer data extraction: frontmatter metadata, section summaries, key paragraphs
+- 5-minute cache with `--refresh` override
+- Symlink-aware directory scanning
+- Bilingual output (auto-detect Chinese/English from user input)
+- `README.md` with install instructions and architecture overview
+- `LICENSE` (MIT)
+- `CONTRIBUTING.md`

package/CONTRIBUTING.md

@@ -0,0 +1,51 @@
+# Contributing to skill-guide
+
+Thanks for your interest! Here's how to contribute.
+
+## Bug Reports
+
+Open an issue with:
+- What you expected to happen
+- What actually happened
+- Your OS and Node.js version (`node --version`)
+- The scanner output if relevant (`node scan-skills.js --list 2>&1`)
+- Doctor output (`node skill-guide.js --doctor`)
+
+## Feature Requests
+
+Open an issue describing the use case. Good requests explain **who** needs it and **why**, not just what.
+
+## Pull Requests
+
+1. Fork the repo
+2. Create a branch: `git checkout -b feat/your-feature`
+3. Make changes — keep the zero-dependency constraint
+4. Test: `npm test` (runs syntax checks, unit tests, and scanner smoke tests)
+5. Commit with conventional commits: `feat:`, `fix:`, `docs:`
+6. Open a PR
+
+## Constraints
+
+- **Zero npm dependencies** — only Node.js built-ins (`fs`, `path`, `os`, `crypto`, `child_process`)
+- **Single-file scanner** — `scan-skills.js` stays as one file
+- **SKILL.md format** — must follow Claude Code skill frontmatter conventions
+- **No external network calls** — scanner reads local files only
+
+## Development
+
+```bash
+# Run the full test suite
+npm test
+
+# Test the scanner
+node scan-skills.js --list
+node scan-skills.js --skill investigate
+node scan-skills.js --search security
+node scan-skills.js --full
+node scan-skills.js --refresh --list
+
+# Test the CLI
+node skill-guide.js --open
+node skill-guide.js --lang zh --open
+node skill-guide.js --doctor
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 skill-guide contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,236 @@
+<p align="center">
+  <img src="https://img.shields.io/badge/Zero%20Dependencies-Node.js-6ee7b7?style=flat-square" />
+  <img src="https://img.shields.io/badge/Output-HTML%20Slides-f0abfc?style=flat-square" />
+  <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" />
+</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.
+
+<p align="center">
+  <a href="https://gtskevin.github.io/skill-guide/"><strong>Live Demo</strong></a>
+  ·
+  <a href="#quick-start">Try it now</a>
+  ·
+  <a href="#install-methods">Install</a>
+  ·
+  <a href="#how-it-works">How it works</a>
+</p>
+
+```bash
+npx skill-guide --open        # ← that's it. HTML slides open 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.
+
+**4 modes:**
+
+| 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 |
+
+## Platform Support
+
+| Platform | Status | Scanned paths |
+|----------|--------|---------------|
+| **Claude Code** | Supported | `~/.claude/skills`, `~/.claude/plugins/marketplaces` |
+| **Codex** | Supported | `~/.codex/skills`, `$CODEX_HOME/skills`, Codex plugin cache |
+| **OpenAI system skills** | Supported | `$CODEX_HOME/skills/.system` as a separate source |
+| **cc-switch** | Supported | `~/.cc-switch/skills` |
+| **Agent Skills** | Compatible | Standard `SKILL.md` skill folders |
+
+## Screenshots
+
+![skill-guide social preview](social-preview.png)
+
+<table>
+  <tr>
+    <td><img src="demo-cover.png" alt="Cover slide" width="400" /></td>
+    <td><img src="demo-categories.png" alt="Category map" width="400" /></td>
+  </tr>
+  <tr>
+    <td align="center"><em>Cover — total count & sources</em></td>
+    <td align="center"><em>Category map — grouped cards</em></td>
+  </tr>
+  <tr>
+    <td><img src="demo-highlights.png" alt="Top picks" width="400" /></td>
+    <td><img src="demo-reference.png" alt="Quick reference" width="400" /></td>
+  </tr>
+  <tr>
+    <td align="center"><em>Top picks — best skills</em></td>
+    <td align="center"><em>Quick reference table</em></td>
+  </tr>
+</table>
+
+## Quick Start
+
+**1. Try instantly** — no install needed:
+```bash
+npx skill-guide --open
+```
+
+**2. Install for Claude Code:**
+```bash
+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 --full --open                 # Generate a full manual
+npx skill-guide --doctor                      # Diagnose your setup
+```
+
+## Install Methods
+
+```bash
+# Claude Code: npx skills (recommended)
+npx skills add gtskevin/skill-guide
+
+# Claude Code: manual symlink
+git clone https://github.com/gtskevin/skill-guide.git
+ln -s $(pwd)/skill-guide ~/.claude/skills/skill-guide
+
+# Claude Code: direct download
+mkdir -p ~/.claude/skills/skill-guide
+curl -sL https://github.com/gtskevin/skill-guide/archive/refs/heads/main.tar.gz | tar xz --strip-components=1 -C ~/.claude/skills/skill-guide
+
+# Codex: manual symlink
+git clone https://github.com/gtskevin/skill-guide.git
+mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
+ln -s "$(pwd)/skill-guide" "${CODEX_HOME:-$HOME/.codex}/skills/skill-guide"
+```
+
+## Usage Examples
+
+### Run as a CLI
+```bash
+npx skill-guide --open
+npx skill-guide --search security --open
+npx skill-guide --skill test-driven-development --open
+npx skill-guide --format json
+npx skill-guide --doctor
+```
+
+### Discover all your skills
+```
+/skill-guide
+```
+Or say: "What skills do I have?" / "帮我看看我有哪些技能"
+
+In Codex, you can also say: "What Codex skills do I have?"
+
+### Deep-dive one skill
+```
+/skill-guide investigate
+```
+Or say: "Tell me about the TDD skill" / "介绍一下 investigate 技能"
+
+### Find the right skill
+```
+Which skill should I use for code review?
+```
+Or: "帮我推荐一个做测试的技能"
+
+### Generate a full manual
+```
+/skill-guide all
+```
+
+## How it works
+
+```
+skill-guide/
+├── SKILL.md             # Skill definition + HTML generation rules
+├── 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
+```
+
+1. `scan-skills.js` scans Claude Code, Codex, cc-switch, and plugin skill directories; parses YAML frontmatter; extracts sections and key paragraphs
+2. `skill-guide.js` turns scanner JSON into deterministic HTML slides with scroll-snap navigation, keyboard controls, and animations
+3. `SKILL.md` lets Claude Code and Codex invoke the same CLI from natural language
+4. Output opens in your browser — zero config, zero dependencies
+
+### Scanner modes
+
+| Flag | Purpose | Data |
+|------|---------|------|
+| `--list` | Discovery | Name + description + category |
+| `--skill <name>` | Deep-dive | Full metadata + sections + key paragraphs |
+| `--search <query>` | Recommendations | Matching skills with full data |
+| `--full` | Complete manual | All skills with full data |
+| `--refresh` | Force re-scan | Ignores 5-min cache |
+
+### CLI flags
+
+| Flag | Purpose |
+|------|---------|
+| `--open` | Open the generated HTML in your browser |
+| `--output <file>` | Save HTML to a specific path |
+| `--format html,json` | Choose HTML slides or raw scanner JSON |
+| `--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) |
+| `--doctor` | Check paths, sources, and scan counts |
+
+### Doctor checks
+
+`npx skill-guide --doctor` reports Node.js version, Claude Code and Codex skill paths, source counts, duplicate skill names, malformed skill files, and suggested install paths.
+
+### Auto-categorization
+
+Skills are automatically sorted into 9 categories: `testing`, `design`, `security`, `documentation`, `automation`, `deployment`, `code-quality`, `development`, `other`.
+
+## Language Support
+
+Automatic — ask in any language, get output in that language. No configuration needed.
+
+- **English** — default
+- **Chinese** — built-in (`--lang zh`)
+- **Japanese, Korean, French, German, Spanish, ...** — agent-side translation (works in Claude Code and Codex)
+
+## Why skill-guide?
+
+- **The only skill that maps your skills** — scans Claude Code, Codex, cc-switch, and plugin sources in one visual overview
+- **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.
+- **Smart caching** — 5-minute TTL so repeated queries are instant
+- **5 seconds to "wow"** — `npx skill-guide --open` is all you need
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## Roadmap
+
+- [ ] `--share` — generate a shareable standalone HTML or Markdown summary
+- [ ] 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).
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,266 @@
+---
+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.
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+---
+
+# Skill Guide
+
+## 1. When to Use
+
+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.
+
+**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"
+
+## 2. Mode Detection
+
+Determine the mode from user input:
+
+| 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` |
+
+**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
+
+## 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.

package/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "Skill Guide"
+  short_description: "Visual map of installed Agent Skills"
+  brand_color: "#818CF8"
+  default_prompt: "Use $skill-guide to show my installed Agent Skills and recommend which ones fit my current work."
+
+policy:
+  allow_implicit_invocation: true

package/bin/skill-guide

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+'use strict';
+
+require('../skill-guide.js');