Skip to content

feat: 支持 SKILL.md 中配置 priority 字段控制 skill 展示排序 #4136

@yiliang114

Description

@yiliang114

What would you like to be added? / 功能描述

在 SKILL.md frontmatter 中增加一个可选的 priority 字段(数字类型,值越大越靠前),让 skill 作者可以自定义 skill 在以下场景中的展示顺序:

  • Skill 工具的 <available_skills> 列表(模型看到的 skill 列表)
  • /skills 命令输出
  • /help 中的 slash command 列表
  • Tab 自动补全

未设置 priority 的 skill 保持现有字母序逻辑作为 fallback。

---
name: my-important-skill
description: 一个重要的 skill
priority: 100
---

Why is this needed? / 为什么需要

当前所有 skill 在所有展示场景中都是纯字母序排列,skill 作者无法控制排序。这导致:

  1. 重要的 skill 被淹没:比如一个项目可能有 10+ 个 skill,但最常用的只有 2-3 个,用户希望这些排在列表前面,减少模型选择错误
  2. 列表过长时体验差:模型在 <available_skills> 中看到的是无差别字母序列表,没法根据重要性判断优先级
  3. 已有基础设施:qwen-code 的 SlashCommand 类型已经有 completionPriority 字段(types.ts:303),自动补全排序也已经使用该字段(useSlashCompletion.ts:242, commandUtils.ts:287),只需打通到 SKILL.md 即可

Additional context / 补充信息

竞品调研

Agent SKILL.md priority 字段 当前排序逻辑
qwen-code 纯字母序 (localeCompare)
claude-code (Anthropic) 按加载顺序,无排序
codex (OpenAI) Scope(Repo > User > System > Admin)→ 字母序
opencode 无(待确认) 继承自 claude-code,大概率相同

目前主流 code agent 都不支持 skill 作者通过 SKILL.md 配置展示优先级。qwen-code 可以作为首个实现该功能的 agent。

关于 SKILL.md 格式兼容性

需要说明的是,虽然都叫 SKILL.md,但 qwen-code/claude-code 与 Codex 已分化为不同的 frontmatter 体系:

frontmatter 字段 Codex qwen-code
name, description
allowed-tools, hooks, model
argument-hint, when_to_use
disable-model-invocation, paths

Codex 的规范甚至明确要求 "Do not include any other fields in YAML frontmatter",而 qwen-code 已有大量自有扩展。添加 priority 字段是 qwen-code 生态的自然延伸,不存在格式兼容性问题。

涉及的改动点

  1. SkillConfig 类型 (packages/core/src/skills/types.ts) — 新增 priority?: number
  2. SKILL.md frontmatter 解析 (packages/core/src/skills/skill-manager.ts:600-694) — 解析 priority 字段
  3. SkillManager.listSkills() 排序 (packages/core/src/skills/skill-manager.ts:234) — 从纯 localeCompare 改为先按 priority 降序再按字母序
  4. Skill loader 桥接 — 将 priority 映射到 SlashCommand.completionPriority

Metadata

Metadata

Assignees

Labels

Type

No type
No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions