Inspect, find, and review your installed Agent Skills across Codex and Claude Code.

Live Demo · Quick Start · npm · FAQ

[!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

⏱️ Get started in 30 seconds

No installation is required for the CLI:

npx skill-guide

The dashboard opens in your browser. The terminal also prints a local summary:

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

What It Can Tell You

skill-guide is a local inventory, discovery, and pre-use review tool. It deliberately separates evidence from inference.

| 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. |

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:

What Skills do I already have for code review?
Show me how the test-driven-development Skill is designed to work.
帮我看看我有哪些 Codex Skills，并找出描述信息较少、值得人工复核的项目。

Install as an Agent Skill

For Claude Code:

npx skills add gtskevin/skill-guide

For Codex:

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"

# 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

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 | | cc-switch | Supported | ~/.cc-switch/skills | | Agent Skills | Compatible | Standard SKILL.md folders |

How It Works

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"]

The scanner uses Node.js built-ins only:

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.

[!WARNING] skill-guide does not silently delete, install, or modify your Skills. Review prompts require human judgment.

FAQ

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.

Not yet. The current release scans local metadata. Reliable invocation tracking requires runtime logs or platform integrations.

No. It is a rough estimate based on description text. Runtime token usage depends on the platform, model, loaded context, and execution path.

No. Warnings are review candidates. Read the Skill, check its source, and confirm your actual needs before changing anything.

Dashboard labels are built in for English and Chinese. Agents can summarize the result in other languages without rewriting the generated HTML.

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for the zero-dependency constraint and test commands.

License

MIT