skills-bundle

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skills Bundle

Overview

概述

Decompose a user's project goal into multi-dimensional skill requirements, search the skill ecosystem, then intelligently filter results against user intent before recommending. Uses a Search → Inspect → Analyze pipeline to avoid irrelevant recommendations.

Core problem: When a user says "I want to build X", naive keyword search returns skills that match the keyword but not the intent. For example, searching "ui" for a game project returns web UI skills instead of game UI skills. This skill solves that by adding a context-aware filtering step.

将用户的项目目标拆解为多维度的Skill需求，搜索Skill生态系统，然后根据用户意图智能过滤结果再进行推荐。采用“搜索→检查→分析”的流程，避免无关推荐。

**核心问题：**当用户说“我想构建X”时，简单的关键词搜索会返回匹配关键词但不符合用户意图的Skill。例如，为游戏项目搜索“ui”时，会返回Web UI Skill而非游戏UI Skill。本Skill通过添加上下文感知过滤步骤解决了这个问题。

When to Use

使用场景

User describes a complex project goal (e.g., "build a React mobile app")
User asks "what skills do I need for X"
User wants to batch install/manage/clean up skills
User wants to bootstrap a new project with the right skill set

Not for: Finding a single specific skill — just use

npx skills find

directly.

用户描述复杂项目目标（例如：“构建一个React移动应用”）
用户询问“做X需要哪些Skill”
用户想要批量安装/管理/清理Skill
用户想要使用合适的Skill集合启动新项目

**不适用场景：**查找单个特定Skill — 直接使用

npx skills find

即可。

Core Pipeline

核心流程

User Goal → Decompose → Search → Inspect → Analyze & Filter → Present → Install

用户目标 → 拆解需求 → 搜索 → 检查 → 分析与过滤 → 展示结果 → 安装

Workflow

工作流

Step 1: Decompose Requirements

步骤1：拆解需求

Understand the user's project goal and decompose into two layers:

Layer 1 — Essential: Skill domains the project cannot do without — derived from the user's explicit requirements and the hard dependencies of the project type (e.g., a game project inherently needs a game engine, asset management, etc.). Layer 2 — Extended: Not strictly required, but significantly improves project quality (e.g., code style, documentation generation). Only expand dimensions relevant to the project type — a CLI tool doesn't need "UI design".

Present the decomposition to the user for confirmation. Always respond in the user's language — if the user writes in Chinese, all output (decomposition, tables, explanations) should be in Chinese; if in English, respond in English.

For each layer, generate context-aware search keywords. Keywords should be specific to the project domain, not generic:

Bad (generic)	Good (context-aware)
`ui`	`game-ui` , `game-hud`
`assets`	`game-assets` , `sprite` , `pixel-art`
`testing`	`game-testing` , `playwright`
`performance`	`webgl-performance` , `game-optimization`

Rule: Always prefix generic keywords with the project domain when a generic term is ambiguous. If the domain-prefixed search returns no results, fall back to the generic keyword but mark it for careful filtering in Step 3.

理解用户的项目目标，并将其拆解为两层：

**第一层 — 核心需求：**项目必不可少的Skill领域 — 从用户的明确需求和项目类型的硬依赖中衍生（例如，游戏项目本质上需要游戏引擎、资源管理等Skill）。 **第二层 — 扩展需求：**并非严格必需，但能显著提升项目质量（例如，代码风格、文档生成）。仅扩展与项目类型相关的维度 — CLI工具不需要“UI设计”Skill。

将拆解结果呈现给用户确认。始终使用用户的语言回复 — 如果用户用中文提问，所有输出（拆解结果、表格、说明）都要用中文；如果用英文提问，则用英文回复。

为每一层生成上下文感知的搜索关键词。关键词应针对项目领域，而非通用词汇：

错误示例（通用）	正确示例（上下文感知）
`ui`	`game-ui` , `game-hud`
`assets`	`game-assets` , `sprite` , `pixel-art`
`testing`	`game-testing` , `playwright`
`performance`	`webgl-performance` , `game-optimization`

**规则：**当通用术语存在歧义时，始终为其添加项目领域前缀。如果带领域前缀的搜索无结果，则回退到通用关键词，但要在步骤3中标记为需要仔细过滤。

Step 2: Multi-round Search

步骤2：多轮搜索

CRITICAL: You MUST run these commands yourself via your Shell/terminal tool. Do NOT guess skills from memory. Do NOT skip this step.

Run

npx skills find <keyword>

for each keyword from Step 1. Run searches in parallel when possible (chain with

&&

Collect all

owner/repo@skill

entries and their URLs from the output. Deduplicate by skill name. Per keyword, only take the top 5 results (or all if fewer than 5) —

npx skills find

already returns results in relevance order.

**重要提示：你必须通过Shell/终端工具自行运行这些命令。**不要凭记忆猜测Skill，不要跳过此步骤。

为步骤1中的每个关键词运行

npx skills find <keyword>

。尽可能并行运行搜索（用

&&

串联）。

收集所有

owner/repo@skill

条目及其输出中的URL。按Skill名称去重。每个关键词仅取前5个结果（如果不足5个则取全部）—

npx skills find

已按相关性排序返回结果。

Step 3: Inspect & Analyze (Sub-agent Filtering)

步骤3：检查与分析（子Agent过滤）

This is the critical step that prevents irrelevant recommendations.

For each unique repository found in Step 2, launch a sub-agent (Task tool) to:

Fetch the skill's detail page at
```
https://skills.sh/<owner>/<repo>/<skill>
```
using WebFetch
Read the skill's description, content, and Weekly Installs count (shown at the bottom of the page)
Score relevance against the user's original goal on a 1-5 scale, considering both content fit and community adoption:
- 5: Directly addresses a core need, well-maintained (high installs)
- 4: Strongly relevant, covers an important aspect
- 3: Somewhat relevant, could be useful
- 2: Tangentially related, different domain
- 1: Irrelevant despite keyword match
- Adoption bonus: When two skills cover similar functionality, prefer the one with significantly higher Weekly Installs — it signals better quality, maintenance, and community validation.
- Low adoption caution: A skill with very few installs (< 100/week) should be noted but not automatically excluded — it may be new or niche.
Return: skill name, source (
```
owner/repo@skill
```
), one-line description, weekly installs, relevance score, and a brief reason

Sub-agent prompt template:

Analyze whether this skill is relevant for the user's project goal.

User's goal: "<user's original request>"
Project type: "<detected project type, e.g. 'browser-based 2D game'>"

Skill to evaluate: <owner/repo@skill>
Skill URL: https://skills.sh/<owner>/<repo>/<skill>

Fetch the skill URL and read its full description and Weekly Installs count. Then score its relevance (1-5) against the user's goal, factoring in community adoption. Return a JSON object:
{
  "name": "<skill-name>",
  "source": "<owner/repo@skill>",
  "description": "<one-line description from the skill page>",
  "weekly_installs": <number>,
  "score": <1-5>,
  "reason": "<why this score, mention installs if it influenced the decision>"
}

Parallelism: Launch sub-agents concurrently to inspect skills in parallel.

Filtering threshold: Only keep skills with score >= 3. Present score 5 and 4 as "Recommended", score 3 as "Optional".

这是避免无关推荐的关键步骤。

针对步骤2中找到的每个唯一仓库，启动子Agent（任务工具）执行以下操作：

使用WebFetch获取Skill详情页：

https://skills.sh/<owner>/<repo>/<skill>

读取Skill的描述、内容和周安装量（显示在页面底部）
根据用户原始目标评分相关性，评分范围1-5分，同时考虑内容匹配度和社区认可度：
- 5分：直接满足核心需求，维护良好（安装量高）
- 4分：高度相关，覆盖重要方面
- 3分：部分相关，可能有用
- 2分：略微相关，属于不同领域
- 1分：无关，仅关键词匹配
- **认可度加分：**当两个Skill功能相似时，优先选择周安装量明显更高的那个 — 这代表更好的质量、维护状态和社区验证。
- **低认可度注意：**周安装量极低（<100次）的Skill应标注，但不要自动排除 — 它可能是新Skill或 niche Skill。
返回：Skill名称、来源（
```
owner/repo@skill
```
）、单行描述、周安装量、相关性评分和简短理由

子Agent提示模板：

分析此Skill是否与用户的项目目标相关。

用户目标："<用户原始请求>"
项目类型："<检测到的项目类型，例如'浏览器端2D游戏'>"

待评估Skill：<owner/repo@skill>
Skill URL：https://skills.sh/<owner>/<repo>/<skill>

获取Skill URL并读取其完整描述和周安装量。然后根据用户目标为其相关性评分（1-5分），同时考虑社区认可度。返回JSON对象：
{
  "name": "<skill-name>",
  "source": "<owner/repo@skill>",
  "description": "<来自Skill页面的单行描述>",
  "weekly_installs": <数字>,
  "score": <1-5>,
  "reason": "<评分理由，若安装量影响了决策请提及>"
}

**并行处理：**同时启动多个子Agent，并行检查Skill。

**过滤阈值：**仅保留评分≥3分的Skill。将5分和4分标记为“推荐”，3分标记为“可选”。

Step 4: Present Results

步骤4：展示结果

Group filtered results by layer (Essential / Extended) and by confidence:

undefined

按层级（核心/扩展）和置信度分组展示过滤后的结果：

undefined

Recommended Skills for: <user's goal>

为你推荐的Skill：<用户目标>

Essential

核心需求

#	Skill	Description	Installs/wk	Relevance	Reason
1	owner/repo@skill	...	1.8K	★★★★★	...
2	owner/repo@skill	...	500	★★★★☆	...

序号	Skill	描述	周安装量	相关性	理由
1	owner/repo@skill	...	1.8K	★★★★★	...
2	owner/repo@skill	...	500	★★★★☆	...

Extended

扩展需求

#	Skill	Description	Installs/wk	Relevance	Reason
3	owner/repo@skill	...	2.1K	★★★★☆	...

序号	Skill	描述	周安装量	相关性	理由
3	owner/repo@skill	...	2.1K	★★★★☆	...

Optional

可选

#	Skill	Description	Installs/wk	Relevance	Reason
4	owner/repo@skill	...	80	★★★☆☆	...


**Filtered out (not shown to user):** Skills with score < 3 are silently dropped. If the user asks why something was excluded, explain the relevance mismatch.

Ask user to select by number (e.g., "1,2,3"), "all essential", or "all".

序号	Skill	描述	周安装量	相关性	理由
4	owner/repo@skill	...	80	★★★☆☆	...


**已过滤（不展示给用户）：**评分<3分的Skill会被自动忽略。如果用户询问为何某Skill未被推荐，解释相关性不匹配的原因。

请用户通过序号选择（例如："1,2,3"），或选择“所有核心需求”、“全部”。

Step 5: Generate Install Commands

步骤5：生成安装命令

Generate copy-paste-ready commands based on user selection. Default to project-level installation (no
-g
flag) unless the user explicitly requests global installation.

bash

undefined

根据用户的选择生成可直接复制粘贴的命令。默认使用项目级安装（不带
-g
参数），除非用户明确要求全局安装。

bash

undefined

Essential

核心需求

npx skills add owner/repo@skill -y npx skills add owner/repo@skill -y

Extended

扩展需求

npx skills add owner/repo@skill -y


If the user specifies global installation, use the `-g` flag: `npx skills add <owner/repo@skill> -g -y`.

npx skills add owner/repo@skill -y


如果用户指定全局安装，添加`-g`参数：`npx skills add <owner/repo@skill> -g -y`。

Step 6: Generate Bundle Config

步骤6：生成包配置文件

After installation, generate

.skills-bundle.json

in the project root:

json

{
  "name": "project-name",
  "created": "2026-02-08",
  "description": "User's project goal",
  "skills": {
    "essential": [
      { "name": "skill-name", "source": "owner/repo@skill", "reason": "Why this skill", "score": 5 }
    ],
    "extended": [
      { "name": "skill-name", "source": "owner/repo@skill", "reason": "Why this skill", "score": 4 }
    ]
  }
}

安装完成后，在项目根目录生成

.skills-bundle.json

：

json

{
  "name": "project-name",
  "created": "2026-02-08",
  "description": "用户的项目目标",
  "skills": {
    "essential": [
      { "name": "skill-name", "source": "owner/repo@skill", "reason": "选择此Skill的理由", "score": 5 }
    ],
    "extended": [
      { "name": "skill-name", "source": "owner/repo@skill", "reason": "选择此Skill的理由", "score": 4 }
    ]
  }
}

Bundle Management

包管理

View Installed Skills

查看已安装的Skill

bash

npx skills ls -g          # List global skills
npx skills ls             # List project-level skills
npx skills ls -a cursor   # Filter by agent

bash

npx skills ls -g          # 列出全局Skill
npx skills ls             # 列出项目级Skill
npx skills ls -a cursor   # 按Agent过滤

Install from Config

从配置文件安装

Read

.skills-bundle.json

, extract all

source

fields, and generate

npx skills add <source> -y

commands (or with

-g

if previously installed globally).

读取

.skills-bundle.json

，提取所有

source

字段，生成

npx skills add <source> -y

命令（如果之前是全局安装则添加

-g

参数）。

Uninstall Bundle

卸载技能包

Read

.skills-bundle.json

, extract all

name

fields, and generate:

bash

npx skills remove <name1> <name2> ... -y

Use

-g

if the skills were installed globally.

读取

.skills-bundle.json

，提取所有

name

字段，生成：

bash

npx skills remove <name1> <name2> ... -y

如果Skill是全局安装的，添加

-g

参数。

Check for Updates

检查更新

bash

npx skills check    # Check for available updates
npx skills update   # Update all installed skills

bash

npx skills check    # 检查可用更新
npx skills update   # 更新所有已安装的Skill

Quick Reference

快速参考

Action	Command
Search skills	`npx skills find <keyword>`
Install skill (Project)	`npx skills add <owner/repo@skill> -y`
Install skill (Global)	`npx skills add <owner/repo@skill> -g -y`
List installed	`npx skills ls` (add `-g` for global)
Remove skills	`npx skills remove <name1> <name2> -y` (add `-g` for global)
Check updates	`npx skills check`
Update all	`npx skills update`

操作	命令
搜索Skill	`npx skills find <keyword>`
安装Skill（项目级）	`npx skills add <owner/repo@skill> -y`
安装Skill（全局）	`npx skills add <owner/repo@skill> -g -y`
列出已安装Skill	`npx skills ls` （添加 `-g` 查看全局）
卸载Skill	`npx skills remove <name1> <name2> -y` （添加 `-g` 卸载全局Skill）
检查更新	`npx skills check`
更新全部	`npx skills update`

Red Flags — STOP If You Catch Yourself Doing These

注意事项 — 如果你出现以下行为请立即停止

"I cannot run
```
npx skills find
```
" — Yes you can. Use your Shell/terminal tool.
"Based on known/installed skills..." — Wrong. You must search the ecosystem.
Showing skill recommendations without running
```
npx skills find
```
— Start Step 2 over.
Recommending skills without inspecting their descriptions — Start Step 3 over. You must verify each skill's actual content against the user's goal.
Recommending a skill just because its name matches a keyword — Wrong. A skill named "ui-components" is not useful for a game project unless its description confirms game UI support.

“我无法运行
```
npx skills find
```
” — 你可以运行。使用你的Shell/终端工具。
“基于已知/已安装的Skill...” — 错误。你必须搜索Skill生态系统。
未运行
```
npx skills find
```
就展示Skill推荐 — 回到步骤2重新开始。
未检查Skill描述就推荐 — 回到步骤3重新开始。你必须验证每个Skill的实际内容是否符合用户目标。
仅因Skill名称匹配关键词就推荐 — 错误。名为“ui-components”的Skill对游戏项目无用，除非其描述明确支持游戏UI。

Common Mistakes

常见错误

Mistake	Correct Approach
Guess skills from memory	Run `npx skills find` for every keyword
Search one keyword and stop	Use two-layer model for multi-round search
Recommend without inspecting skill content	Fetch and read each skill's description via sub-agent
Use generic keywords that return wrong-domain results	Use domain-prefixed keywords; fall back to generic only with careful filtering
Mix essential and extended without distinction	Separate into Essential / Extended layers so user can choose
Install without keeping records	Generate `.skills-bundle.json`
Skip relevance filtering	Always run Step 3 — it's the most important step

错误行为	正确做法
凭记忆猜测Skill	为每个关键词运行 `npx skills find`
只搜索一个关键词就停止	使用两层模型进行多轮搜索
未检查Skill内容就推荐	通过子Agent获取并阅读每个Skill的描述
使用通用关键词导致返回跨领域结果	使用带领域前缀的关键词；仅在仔细过滤的前提下回退到通用关键词
不区分核心需求和扩展需求	拆分为核心/扩展两层，方便用户选择
安装后不保留记录	生成 `.skills-bundle.json` 配置文件
跳过相关性过滤	始终执行步骤3 — 这是最重要的步骤