Grok Skills 技能系统完全指南：SKILL.md 编写、自动触发与分发实战
【免费下载链接】grok-buildSpaceXAI's coding agent harness and TUI. Fullscreen, mouse interactive, extensible.项目地址: https://gitcode.com/gh_mirrors/gr/grok-build
Skills 是 Grok（本仓库 xai-grok-pager / xai-grok-shell 所实现的编码 Agent 与 TUI）提供的可复用提示包机制，把重复性任务流程固化成一份带元数据的 Markdown 文件，一次编写、反复触发。本文以官方用户指南 08-skills.md 为骨架，结合仓库内技能发现、解析、注入与检查的真实实现，系统讲解技能目录的优先级规则、SKILL.md 的 frontmatter 编写、/create-skill交互式创建、斜杠命令调用、自动触发判定、grok inspect排查，以及插件分发技能的最佳实践。读完你就能在项目或用户级目录里落地一套属于自己的技能库。
什么是 Skills
技能（Skill）本质上是一个包含SKILL.md文件的目录。这个 Markdown 文件的正文告诉 Grok 如何处理某一类任务：分步操作说明、项目约定、工具使用模式等，统统可以固化进去。
它与AGENTS.md的分工是：
- AGENTS.md：面向整个仓库的常驻规则，任何会话都会加载；
- Skill：面向"过于具体、写进 AGENTS.md 太重，但又太长、每次会话重新打一遍不划算"的可重复流程；
- 触发方式：Grok 只在技能与当前任务匹配时才激活它——可以是你主动敲
/skill-name，也可以是模型根据描述自动调用。
从源码结构看，这套机制贯穿两层：发现与解析位于 xai-grok-tools 的 skills 实现（SKILL.md 文件系统扫描与 frontmatter 解析），注入与排序位于 xai-grok-agent 的 prompt/skills.rs（按优先级汇聚各来源、过滤、标记禁用并写入系统提示）。
Skill 的发现位置与优先级
Grok 按下列目录发现技能，优先级从高到低：
| 位置 | 作用域 | 优先级 | 说明 |
|---|---|---|---|
./.grok/skills/、./.grok/commands/ | 本地（CWD） | 最高 | 当前目录技能 / 遗留命令 Markdown |
<repo_root>/.grok/skills/、…/commands/ | 仓库 | 中 | 整个仓库共享 |
~/.grok/skills/、~/.grok/commands/ | 用户 | 最低 | 跨项目个人技能 |
~/.claude/skills/、~/.claude/commands/ | 用户 | 最低 | Claude Code 兼容（可配置） |
./.claude/skills/、./.claude/commands/ | 本地 / 仓库 | 高 | 项目 Claude 技能与旧式自定义斜杠命令 |
~/.cursor/skills/ | 用户 | 最低 | Cursor 兼容（可配置） |
./.cursor/skills/ | 本地 / 仓库 | 高 | 项目 Cursor 技能（启用 cursor 兼容技能时） |
几点关键行为（源码均能印证）：
- 按名称去重：Grok 按技能名去重，高优先级位置的同名技能覆盖低优先级位置。
- 多前缀目录：除了
.grok/，还会在每一层同时扫描.agents/skills/（以及commands/）；并且会沿着工作目录到仓库根之间的每一级目录逐层向上走查。在 prompt/skills.rs 中，完整优先级被描述为：Local（cwd 下的.grok/.agents/.claude）→ 中间层级目录 → Repo（git 根下的.grok/.agents/.claude）→ User（~/.grok、~/.agents、~/.claude）→config.paths附加路径 → Server（注入的服务端同步目录）→ Bundled（内置打包目录，优先级最低）。 - commands/ 目录的扁平规则：
commands/目录下扁平的*.md文件会成为可由用户调用的斜杠命令（文件名主干 = 命令名），与 Claude Code 的旧式自定义命令布局一致。对应实现见 discovery.rs：find_command_paths只做commands/下的非递归扫描，而find_skill_paths对skills/做递归遍历（walk_for_skill_md最多下探 5 层，即MAX_SKILL_WALK_DEPTH = 5）。 - 不遵循
.gitignore：技能与命令的发现不使用.gitignore。处于已知技能根（.grok/、.agents/、.claude/、.cursor/）下的路径只要在磁盘上存在就会加载——团队经常把.claude/**当作仅本地的配置忽略掉，却仍期望/frontend这类项目命令可用。要隐藏技能，请用配置里的[skills] ignore，而不是仓库忽略规则。prompt/skills.rs 的注释明确写着：AGENTS.md 的发现仍遵循 gitignore（那属于仓库内容），而技能根目录不是。 - 供应商默认技能的过滤：Grok 默认会扫描 Claude 与 Cursor 的技能目录。若想停掉某个厂商，可在
~/.grok/config.toml的[compat.cursor]或[compat.claude]下把对应skills单元置为false，或把环境变量GROK_CURSOR_SKILLS_ENABLED、GROK_CLAUDE_SKILLS_ENABLED设为false。详见 Configuration。无论这些开关如何设置，Grok始终过滤掉已知的厂商预置技能，例如 Cursor 的shell、canvas、statusline。这一点在 discovery.rs 中有一份完整 denylist：Cursor 侧是babysit、canvas、create-hook、create-rule、create-skill、create-subagent、loop、migrate-to-skills、sdk、shell、split-to-prs、statusline、update-cli-config、update-cursor-settings；Claude 侧是pdf、docx、xlsx、pptx、skill-creator。注意过滤是按路径判定的——只有物理上位于/.cursor/或/.claude/目录下的同名技能才会被丢弃，你自己在~/.grok/skills/shell里写的技能不受影响。
附加技能目录
通过~/.grok/config.toml的[skills]段，可以追加目录、排除路径或单独禁用技能：
[skills] paths = ["~/my-team-skills"] # 额外扫描的目录 ignore = ["~/my-team-skills/wip"] # 排除的路径（完全隐藏） disabled = ["wip-skill"] # 保留列表但停用的技能名paths中每一项可以是一个SKILL.md文件，也可以是一个会被递归遍历的目录；ignore完全隐藏技能；disabled让技能留在列表里，但既不进系统提示，也不允许调用；paths与ignore接受文件系统路径并支持~展开；disabled接受技能名。
这些字段与源码中SkillsConfig一一对应：见 prompt/skills.rs，其中还额外包含由启动器注入的server_skill_dirs（Server 作用域）与bundled_skill_dirs（Bundled 作用域）。ignore的匹配是前缀匹配：在list_skills_with_plugins中，任何解析路径以 ignore 条目开头的技能都会被整体过滤掉。
补充：shell 侧还支持
[paths] extra_skill_dirs数组作为[skills].paths的补充来源，见 extensions/skills.rs；在grok inspect的输出中会被标记为config来源。
创建 Skill
目录结构
每个技能拥有自己的目录，内含一个SKILL.md：
~/.grok/skills/ commit/ SKILL.md review-pr/ SKILL.md deploy/ SKILL.mdSKILL.md 格式
技能文件 = YAML frontmatter + Markdown 正文：
--- name: commit description: Create well-formatted git commits following conventional commit standards. Use when the user wants to commit changes or asks for /commit. --- # Git Commit Skill Review staged changes and create a commit with a clear, conventional message. ## Steps 1. Run `git diff --staged` to see changes 2. Summarize what changed and why 3. Create commit message following conventional commits format 4. Run `git commit -m "..."` with the message核心 frontmatter 字段
| 字段 | 说明 |
|---|---|
name | 技能标识。使用小写字母、数字和连字符，最长 64 字符。Grok 会把空格和下划线规范化为连字符。省略时使用技能目录名。 |
description | 技能做什么、何时使用。Grok 依据它决定是否自动调用技能。省略时使用正文第一段。 |
description必须写得具体——它直接决定技能的自动触发时机。把触发短语和使用场景都写进去。
可选 frontmatter 字段
多词键使用 kebab-case（单词键如model原样书写）。
| 字段 | 说明 |
|---|---|
when-to-use | 自动调用的触发短语，与description分离维护。 |
allowed-tools | 技能用到的工具，YAML 列表或逗号/空格分隔的字符串。 |
argument-hint | 斜杠命令自动补全中显示的提示文本（例如commit message）。 |
user-invocable | 是否可当作斜杠命令运行。默认true；设为false从斜杠命令中隐藏。（要禁止模型调用，用disable-model-invocation。） |
disable-model-invocation | 为true时只有你的斜杠命令能运行该技能——模型不能自动调用。默认false。 |
model | 运行该技能时的模型覆盖。 |
effort | 推理强度（reasoning-effort）覆盖。 |
license | 许可证标识（例如Apache-2.0）。 |
compatibility | 环境要求（例如Requires git, docker, jq）。 |
metadata | 任意字符串键值对。metadata.author与metadata.short-description会被 Grok 提升用于展示。 |
解析器的容错与约束（源码级细节）
discovery.rs 是技能解析的单一汇聚点，有几个值得注意的实现细节：
- 命名规范化：
normalize_skill_name会把名字转小写，把任何非[a-z0-9]字符（空格、下划线、点号等）替换为连字符，折叠连续连字符并去掉首尾连字符，例如tool-v1.2会被规范化为tool-v1-2，而不是直接丢弃该技能（discovery.rs）。is_valid_skill_name校验：非空、不超过 64 字符、不以连字符开头/结尾、不含--、只含小写字母数字与连字符。 - 描述兜底策略：
description缺失时，解析器用 pulldown-cmark 解析正文，优先取第一个散文段落；只有没有散文段落时才退回标题，最后退回技能名。表格、列表、代码块和引用块会被跳过，避免把结构内容误当描述（discovery.rs）。 - YAML 容错三级恢复：frontmatter 解析失败时，先尝试给含 YAML 指示符的值加引号重试，仍失败则对
name、description、when-to-use做逐行标量恢复，绝不因为一个字段写坏就丢掉整个 frontmatter（discovery.rs）。 - 工具列表解析：
allowed-tools支持字符串或 YAML 列表，且会保留括号内的整体，例如Bash(git diff:*)不会被拆分（discovery.rs）。 paths门控：frontmatter 还支持一个原文档未展开的paths字段——glob 模式列表，用来限制技能在哪些路径下才会被 surface；**或空值表示总是出现。解析时{a,b}花括号组会保持完整交给 gitignore 匹配器展开（discovery.rs）。- 体积上限：
MAX_NAME_LEN = 64、MAX_DESCRIPTION_LEN = 1024、MAX_FRONTMATTER_BYTES = 4096、MAX_BODY_PEEK_BYTES = 2048（discovery.rs）。
用 /create-skill 创建技能
/create-skill命令会以交互方式引导你完成新技能的创建：Grok 询问你的需求、起草文件并写入磁盘。
工作流程
运行/create-skill后，Grok 依次：
- 收集需求：询问技能名、保存的作用域、以及你想固化的工作流描述。名字用 2–64 字符的小写字母、数字和连字符，且以字母或数字开头和结尾。
- 起草描述：写出
description，包含技能做什么、触发短语、斜杠命令名。你批准或编辑草稿后继续。 - 创建技能目录：创建
<scope>/.grok/skills/<name>/目录，需要时还会创建scripts/或references/子目录。 - 写入 SKILL.md：写入 frontmatter（
name和description）以及 Markdown 正文，连同所需的辅助文件。 - 校验并确认：回读文件、确认写入正确，并告诉你如何运行该技能。
选择作用域
Grok 会询问把技能保存到哪里：
- Project（项目）：
<repo_root>/.grok/skills/<name>/—— 仅当前仓库可用，可通过版本控制与队友共享。在 git 仓库内 Grok 推荐此作用域。 - User（用户）：
~/.grok/skills/<name>/—— 所有项目可用。
若要把技能分发给整个团队或组织，可以打包进插件并通过市场发布。参见 Create your own marketplace 与 Distribute across an organization。
新技能会在几秒内出现在斜杠菜单中——因为 Grok 会在磁盘文件变化时自动重载技能。仓库为此实现了文件监听：技能目录的集合由 collect_skill_config_dirs 统一提供给发现逻辑与文件 watcher，保证二者对"哪些目录重要"的认知一致。
使用 Skills
按名称运行
每个技能都是一个以技能名命名的斜杠命令，直接输入名字即可：
/commit # 运行 "commit" 技能 /review-pr # 运行 "review-pr" 技能运行技能会把其指令载入当前对话，并引导模型遵循。要传参数，在名字后追加即可：
/commit fix the build浏览技能：输入/打开斜杠命令菜单，Grok 会列出所有内置命令和技能并随输入过滤。命令行查看则用grok inspect（见下文"查看技能详情"）。
限定名称（Qualified Names）
当技能名与另一技能或内置命令冲突时，Grok 让两者都可调用：内置命令保留裸名（/login、/compact等），技能则以作用域前缀的限定名呈现——local:、repo:、user:或插件名：
/local:commit # 来自 ./.grok/skills/ 的 "commit" 技能 /user:commit # 来自 ~/.grok/skills/ 的 "commit" 技能 /acme:login # 名为 "login" 的插件技能（内置 /login 不受影响）在斜杠菜单中输入/login会同时显示两行，右侧有右对齐的built-in或skill · plugin-name徽标便于区分。想要裸名/name，就重命名技能（或它的目录）。
grok inspect会给冲突技能打上[collides with /login → /acme:login]标签。该逻辑实现在 inspect/mod.rs：通过统计斜杠名出现次数与内置命令集比对，得出collides_with（被争夺的名字）与invocable_as（应输入的限定命令）。
自动触发
当识别到相关任务时，Grok 可以自行调用技能：它会拿你的提示与技能的description、when-to-use字段做匹配，所以两者都要写清楚触发情境。
例如，某技能 description 写的是 "Use when the user wants to commit changes"，那么你说 "commit my changes" 就可能自动触发该技能。若想强制显式斜杠命令、禁止自动触发，在 frontmatter 中设置：
disable-model-invocation: true从实现看，自动触发与系统提示注入是同一链路：list_skills_with_plugins把各来源技能合并、应用ignore过滤、处理插件技能合并，最后把disabled名单中的技能标记enabled = false，排除出系统提示与技能工具调用（prompt/skills.rs）。优先级合并遵循"本地 > 仓库 > 用户 > 附加路径 > Server > Bundled"，同名技能高优先级覆盖低优先级，而插件技能即使与原生技能同名也不会覆盖原生技能，只会保留在plugin:name限定形式下。
查看技能详情
运行grok inspect查看 Grok 发现的所有技能以及其余配置：
grok inspect # 人类可读摘要 grok inspect --json # 机器可读报告人类可读输出中，Skills 一节会列出每个技能的名称与来源——project、user、bundled、config（[skills].paths条目）、server（托管工作区中从技能商店同步来的）、或plugin: <name>。经[skills].disabled禁用或来自被禁供应商面的技能会打上[disabled]标记。
该报告与真实会话遵守同样的[skills]配置规则：paths中的技能被列出，ignore前缀下的技能被隐藏，disabled名单中的技能保留但标记为[disabled]。
--json报告包含每个技能的完整细节：name、description、source（含 SKILL.md 路径）以及userInvocable标志。裸斜杠名被内置命令或其他技能争夺的技能，还会包含collidesWith（被争夺的名字）与invocableAs（要输入的限定命令）——对应 inspect/mod.rs 中的SkillEntry字段。
内置技能与插件技能
Grok 把平台技能与个人技能分开分发：
- 内置技能缓存在
~/.grok/bundled/skills/下，Grok 从不把它们写入~/.grok/skills/；同名的本地、仓库或用户技能会覆盖内置副本。grok inspect会按实际来源标注每个定义。 - 插件技能：安装带技能的插件后，它们与用户、项目技能并列出现。
grok inspect会把每个插件技能标注为plugin: <name>。 - 同名插件技能不会覆盖原生技能，它保持在
plugin:name限定形式下可用。
关于安装提供技能的插件，详见 Plugins guide。
从实现看，插件技能的收集走独立路径：collect_plugin_skills遍历插件注册表（prompt/skills.rs），插件的作用域（CliOverride→ Local、Project→ Repo）会决定技能的 scope 归类，plugin_name与plugin_version会被记录在SkillInfo中。
此外，Grok 还提供了一套 ACP 扩展方法用于在会话中动态管理技能配置（extensions/skills.rs）：
x.ai/skills/add/x.ai/skills/remove：把路径加入/移出[skills].paths，路径支持~展开与相对 cwd 解析，随后以 5 秒超时重载全部技能并返回新增/剩余数量；x.ai/skills/reset：把技能配置恢复为默认；x.ai/skills/list/x.ai/skills/config：列出全部技能与当前发现源摘要（自动发现目录、自定义路径、忽略项、加载总数）；x.ai/skills/toggle：按名字启用/禁用技能（即[skills].disabled名单的增删）。
其中resolve_skill_path（extensions/skills.rs）负责把~/...、相对路径、..统统解析成绝对路径再写入配置，保证从任何 cwd 都生效。
最佳实践
- 写具体的 description。description 驱动自动触发。"Create git commits" 太笼统；"Create well-formatted git commits following conventional commit standards. Use when the user wants to commit changes or asks for /commit." 要好得多。
- 包含具体步骤。给 Grok 一条清晰有序的流程，技能才最好用。
- 按名字引用工具。技能依赖特定工具（如
run_terminal_command或search_replace）时，直接点名，模型才知道该用什么。别忘了在allowed-tools里声明。 - 保持技能聚焦。一个工作流一个技能。"deploy" 和 "rollback" 两个技能，好过一个 "deploy-and-rollback"。
- 项目技能纳入版本控制。把
.grok/skills/提交进仓库，全团队受益；~/.grok/skills/里的用户技能保持个人私有、不共享。 - 先跑再依赖。在依赖自动触发之前，先手动
/name调用一次确认技能工作正常。
小结
Grok 的 Skills 机制可以概括为三句话：一个目录 + 一份 SKILL.md（带 frontmatter 元数据与 Markdown 步骤正文）；一套按优先级排布的发现位置（CWD 本地 > 仓库 > 用户 > 附加路径 > 内置，同名高优先级覆盖低优先级）；两种触发方式（用户斜杠命令/name与模型按 description/when-to-use 自动调用）。配合/create-skill交互式创建、grok inspect排查、[skills]配置精细管控，以及插件/市场分发，它可以成为团队沉淀工程流程的标准化载体。深入阅读推荐：发现与解析实现见 discovery.rs，优先级汇聚与系统提示注入见 prompt/skills.rs，会话内动态管理见 extensions/skills.rs，grok inspect报告见 inspect/mod.rs。
【免费下载链接】grok-buildSpaceXAI's coding agent harness and TUI. Fullscreen, mouse interactive, extensible.项目地址: https://gitcode.com/gh_mirrors/gr/grok-build
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
