skill-guide 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,51 @@ 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.4.0] - 2026-06-01
+
+### Added
+- Platform-scoped filtering: all modes (dashboard, doctor, find, review, recommend, share) default to the current agent's skills.
+- Auto-detection via env vars (`CLAUDE_CODE`, `CODEX_AGENT`) or install path.
+- `--platform <claude|codex>` flag to force a specific platform view.
+- `--all` flag to see the full cross-platform inventory.
+- `applyPlatformFilter()` helper for consistent platform filtering across all CLI modes.
+- 8 new tests covering platform detection, filtering, and env var auto-detection.
+
+### Changed
+- Review mode (`--review`) no longer flags cross-agent duplicates as issues — each agent needs its own skill copies.
+- Cover slide title auto-adapts to show "Your Claude Code Skills" or "Your Codex Skills" based on filtered results.
+- `--find` commands in Next Steps slide simplified (removed redundant `--find` flag).
+
+### Fixed
+- `\n` literal rendering in Copy Review Prompt button (replaced inline string with window variable pattern).
+- `--platform` value no longer misinterpreted as a positional `--find` argument.
+
+## [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 +64,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 +79,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

@@ -1,236 +1,230 @@
-<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>
+<div align="center">
 
-```bash
-npx skill-guide --open        # ← that's it. HTML slides open in your browser.
-```
+<picture>
+  <img src=".github/assets/banner.svg" alt="skill-guide — know what your AI agent can do before you trust it" width="800" />
+</picture>
 
-## What it does
+<br />
 
-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.
+[![npm version](https://img.shields.io/npm/v/skill-guide?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/skill-guide)
+[![npm downloads](https://img.shields.io/npm/dm/skill-guide?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/skill-guide)
+[![tests](https://img.shields.io/github/actions/workflow/status/gtskevin/skill-guide/test.yml?branch=main&style=for-the-badge&label=tests)](https://github.com/gtskevin/skill-guide/actions/workflows/test.yml)
+[![license](https://img.shields.io/badge/license-MIT-22c55e?style=for-the-badge)](LICENSE)
 
-**4 modes:**
+**Inspect, find, and review your installed Agent Skills across Codex and Claude Code.**
 
-| 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 |
+[Live Demo](https://gtskevin.github.io/skill-guide/) · [Quick Start](#quick-start) · [npm](https://www.npmjs.com/package/skill-guide) · [FAQ](#faq)
 
-## Platform Support
+</div>
 
-| 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
+> [!NOTE]
+> You installed a useful Skill from someone else. But what will it actually do? When should it activate? Do you already have another Skill for the same job? Is its description heavy enough to deserve a closer look?
+>
+> `skill-guide` gives you a local map before you place uncertain trust in downloaded Agent Skills.
+
+## Highlights
+
+| | Capability | Why it matters |
+|---|---|---|
+| 🔍 | **Inventory your Skills** | See what is installed across Codex, Claude Code, cc-switch, and plugin directories. |
+| 🎯 | **Find a Skill for a task** | Search names, descriptions, and declared triggers before installing another tool. |
+| 📖 | **Inspect how a Skill is designed to work** | Review its source, declared tools, use cases, limitations, and document structure. |
+| 🛡️ | **Review before you trust** | Surface local metadata signals such as sparse descriptions, duplicate sources, and estimated description tokens. |
+| 🎯 | **Platform-scoped views** | Default to your current agent's Skills; use `--platform` or `--all` to switch scope. |
+
+## Quick Start
 
-![skill-guide social preview](social-preview.png)
+> ⏱️ **Get started in 30 seconds**
+
+No installation is required for the CLI:
+
+```bash
+npx skill-guide
+```
+
+The dashboard opens in your browser. The terminal also prints a local summary:
+
+```text
+skill-guide · 338 skills · Local profile: Collector
+
+Health: 68/100
+338 skills · 9/9 categories · ~20.0K description tokens
+Sources: 59 user-directory · 280 plugin-directory
+16 skills have sparse metadata — review descriptions and triggers
+```
+
+> [!IMPORTANT]
+> Token numbers are rough estimates for Skill descriptions, not measured runtime cost. Health output is a local review prompt, not a verdict on quality or safety.
+
+## Demo
+
+<div align="center">
+  <img src="demo.gif" alt="skill-guide scans installed Agent Skills and opens an HTML dashboard" width="760" />
+</div>
 
 <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>
+    <td><img src="demo-cover.png" alt="skill-guide cover slide with local Skill sources" width="400" /></td>
+    <td><img src="demo-categories.png" alt="skill-guide category map grouped by Skill type" 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>
+    <td align="center"><em>Local inventory and sources</em></td>
+    <td align="center"><em>Category map</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>
+    <td><img src="demo-highlights.png" alt="skill-guide review highlights for installed Skills" width="400" /></td>
+    <td><img src="demo-reference.png" alt="skill-guide searchable reference table" width="400" /></td>
   </tr>
   <tr>
-    <td align="center"><em>Top picks — best skills</em></td>
-    <td align="center"><em>Quick reference table</em></td>
+    <td align="center"><em>Review highlights</em></td>
+    <td align="center"><em>Quick reference</em></td>
   </tr>
 </table>
 
-## Quick Start
+## What It Can Tell You
 
-**1. Try instantly** — no install needed:
-```bash
-npx skill-guide --open
-```
+`skill-guide` is a local inventory, discovery, and **pre-use review** tool. It deliberately separates evidence from inference.
 
-**2. Install for Claude Code:**
-```bash
-npx skills add gtskevin/skill-guide
-```
+| Question | What `skill-guide` does today | Boundary |
+|---|---|---|
+| What Skills do I have? | Scans local user, system, cc-switch, and plugin directories. Defaults to the current agent's Skills. | Reports what is visible on the current machine. Use `--all` for cross-platform inventory. |
+| Do I already have a Skill for this task? | Searches names, descriptions, and declared triggers with `--find`. | Returns metadata matches, not a semantic guarantee. |
+| How is this Skill designed to work? | Shows source, declared tools, use cases, limitations, and document sections. | Explains documented intent; it does not execute an audit of every command. |
+| Could Skill descriptions be heavy? | Estimates description tokens and highlights longer descriptions. | Does not measure runtime tokens, API cost, or context injection behavior. |
+| Was a Skill actually invoked? | Not yet. | Runtime invocation tracking requires logging integrations. |
+| Is the output good or cost-effective? | Not yet. | Result quality and actual cost require runtime evidence and evaluation. |
 
-**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
+## Commands
+
+| Goal | Command |
+|---|---|
+| Open your local dashboard | `npx skill-guide` |
+| Find a Skill for a task | `npx skill-guide --find security` |
+| Inspect one Skill | `npx skill-guide --find test-driven-development` |
+| Diagnose local setup | `npx skill-guide --doctor` |
+| Review directory mentions and same-category candidates | `npx skill-guide --recommend` |
+| Generate a shareable local profile | `npx skill-guide --share` |
+| Return structured scanner data | `npx skill-guide --format json` |
+| Focus on one agent's Skills | `npx skill-guide --platform claude` |
+| Include every detected platform | `npx skill-guide --all` |
+
+### Example Prompts
+
+When `skill-guide` is installed as an Agent Skill, try:
+
+```text
+What Skills do I already have for code review?
+Show me how the test-driven-development Skill is designed to work.
+帮我看看我有哪些 Codex Skills，并找出描述信息较少、值得人工复核的项目。
 ```
 
-## Install Methods
+## Install as an Agent Skill
+
+For Claude Code:
 
 ```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
+For Codex:
 
-# Codex: manual symlink
+```bash
 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
+<details>
+<summary>More installation options</summary>
 
-### 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
-```
+# Claude Code: manual symlink
+git clone https://github.com/gtskevin/skill-guide.git
+ln -s "$(pwd)/skill-guide" ~/.claude/skills/skill-guide
 
-### Discover all your 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
 ```
-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 技能"
+</details>
 
-### Find the right skill
-```
-Which skill should I use for code review?
-```
-Or: "帮我推荐一个做测试的技能"
+## Platform Support
 
-### Generate a full manual
-```
-/skill-guide all
-```
+| 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` |
+| cc-switch | Supported | `~/.cc-switch/skills` |
+| Agent Skills | Compatible | Standard `SKILL.md` folders |
 
-## How it works
+## 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
+```mermaid
+flowchart LR
+    A["Local Skill directories"] --> B["scan-skills.js"]
+    B --> C["Parse metadata and document sections"]
+    C --> D["skill-guide.js"]
+    D --> E["Browser-ready HTML dashboard"]
+    C --> F["Search, doctor, and review prompts"]
 ```
 
-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
+The scanner uses Node.js built-ins only:
 
-### Scanner modes
+1. Scan local Skill directories and plugin caches.
+2. Parse frontmatter, descriptions, triggers, declared tools, and selected document sections.
+3. Estimate description tokens and surface deterministic local review prompts.
+4. Render a standalone HTML dashboard that opens in your browser.
 
-| 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 |
+> [!WARNING]
+> `skill-guide` does not silently delete, install, or modify your Skills. Review prompts require human judgment.
 
-### CLI flags
+## FAQ
 
-| 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 |
+<details>
+<summary>Does skill-guide send my local Skills to a server?</summary>
 
-### Doctor checks
+No. Core scanning and dashboard generation run locally with Node.js built-ins. The optional `--recommend` command reads public online directories to show directory mentions.
+</details>
 
-`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.
+<details>
+<summary>Can it tell whether Claude Code or Codex actually invoked a Skill?</summary>
 
-### Auto-categorization
+Not yet. The current release scans local metadata. Reliable invocation tracking requires runtime logs or platform integrations.
+</details>
 
-Skills are automatically sorted into 9 categories: `testing`, `design`, `security`, `documentation`, `automation`, `deployment`, `code-quality`, `development`, `other`.
+<details>
+<summary>Does the token estimate equal my real API cost?</summary>
 
-## Language Support
+No. It is a rough estimate based on description text. Runtime token usage depends on the platform, model, loaded context, and execution path.
+</details>
 
-Automatic — ask in any language, get output in that language. No configuration needed.
+<details>
+<summary>Does a health warning mean I should delete a Skill?</summary>
 
-- **English** — default
-- **Chinese** — built-in (`--lang zh`)
-- **Japanese, Korean, French, German, Spanish, ...** — agent-side translation (works in Claude Code and Codex)
+No. Warnings are review candidates. Read the Skill, check its source, and confirm your actual needs before changing anything.
+</details>
 
-## Why skill-guide?
+<details>
+<summary>Which languages are supported?</summary>
 
-- **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
+Dashboard labels are built in for English and Chinese. Agents can summarize the result in other languages without rewriting the generated HTML.
+</details>
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+Issues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the zero-dependency constraint and test commands.
 
-## 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
+## License
 
-Have an idea? [Open a feature request](https://github.com/gtskevin/skill-guide/issues/new?template=feature_request.yml).
+[MIT](LICENSE)
 
-## License
+---
 
-MIT
+<div align="center">
+  <sub>Built with care by <a href="https://github.com/gtskevin">@gtskevin</a> for developers who want to understand Agent Skills before trusting them.</sub>
+</div>