Grok-Skill-编写安装部署攻略

Grok Skill 编写 · 安装 · 部署完整攻略适用产品：Grok Build TUI / Grok CLI（xAI）文档版本：2026-07目标读者：希望把重复工作流封装为可复用 Skill 的开发者与团队目录概述：Skill 是什么系统架构目录与发现优先级编写 Skill安装与部署调用与运行时行为插件化分发配置与兼容层最佳实践与检查清单故障排查附录：完整模板1. 概述：Skill 是什么Skill是 Grok 的可复用提示词包（prompt package）。它把某一类任务的步骤、约定、工具用法写成SKILL.md，让模型在需要时按同一套流程执行，而不是每次会话重新解释。对比项AGENTS.md / 项目规则Skill普通对话提示作用域整个仓库的长期约定单一可重复工作流一次性触发方式几乎始终注入上下文斜杠命令 / 自动匹配用户每次输入体积宜短可较长、可带子资源受会话限制典型用途编码规范、构建命令发版、Code Review、文档生成临时问答何时写 Skill：流程会重复出现（如 conventional commit、PR 审查、部署检查）步骤比一句话复杂，但又不适合写进全局AGENTS.md希望团队共享同一套操作手册（放进仓库.grok/skills/）何时不要写 Skill：一次性探索、一次性问答仅 1–2 句就能说清的偏好（放进AGENTS.md更合适）2. 系统架构2.1 总体架构图┌──────────────────────────────────────────────────────────────────────────┐ │ 用户交互层 (User Layer) │ │ ┌─────────────┐ ┌──────────────┐ ┌─────────────┐ ┌────────────────┐ │ │ │ Slash 命令 │ │ 自然语言意图 │ │ /skills 菜单 │ │ grok inspect │ │ │ │ /my-skill │ │ 自动匹配触发 │ │ Ctrl+L 等 │ │ 调试与清单 │ │ │ └──────┬──────┘ └──────┬───────┘ └──────┬──────┘ └────────┬───────┘ │ └─────────┼────────────────┼─────────────────┼──────────────────┼──────────┘ │ │ │ │ ▼ ▼ ▼ ▼ ┌──────────────────────────────────────────────────────────────────────────┐ │ Grok Runtime / Agent 核心 │ │ ┌────────────────┐ ┌─────────────────┐ ┌──────────────────────────┐ │ │ │ Skill Registry │──▶│ Description 匹配 │──▶│ System / Skill Prompt │ │ │ │ (名称去重合并) │ │ + 斜杠路由 │ │ 注入当前会话 │ │ │ └───────▲────────┘ └─────────────────┘ └────────────┬─────────────┘ │ │ │ │ │ │ ┌───────┴───────────────────────────────────────────────▼─────────────┐ │ │ │ Skill Discovery Scanner │ │ │ │ 扫描磁盘 → 解析 frontmatter → 应用 ignore/disabled → 注册 slash │ │ │ └───────▲──────────────────▲──────────────────▲──────────────────▲────┘ │ └──────────┼──────────────────┼──────────────────┼──────────────────┼──────┘ │ │ │ │ ┌──────────┴──────┐ ┌─────────┴────────┐ ┌───────┴────────┐ ┌───────┴────────┐ │ Local / Repo │ │ User Home │ │ Bundled │ │ Plugin / Paths │ │ ./.grok/skills │ │ ~/.grok/skills │ │ 内置提取副本 │ │ 插件 额外路径│ │ ./.agents/… │ │ ~/.claude/… │ │ (create-skill │ │ marketplace │ │ ./.claude/… │ │ ~/.cursor/… │ │ help 等) │ │ [skills].paths │ │ ./.cursor/… │ │ │ │ │ │ │ └─────────────────┘ └──────────────────┘ └────────────────┘ └────────────────┘ │ │ │ │ └──────────────────┴──────────────────┴──────────────────┘ │ ▼ ┌───────────────────────┐ │ SKILL.md 包结构 │ │ frontmatter + body │ │ scripts/ references/ │ └───────────────────────┘2.2 运行时调用链路用户输入 │ ├─ 显式 /skill-name [args] │ │ │ ▼ │ 解析 skill 名称（含 local: / user: / plugin: 限定名） │ │ │ ▼ │ 加载 SKILL.md → 将 body 作为指令注入会话 │ │ │ ▼ │ Agent 按步骤调用工具 (shell / 读写文件 / MCP / subagent …) │ └─ 自然语言（如 “帮我提交代码”） │ ▼ 模型阅读各 skill 的 description / when-to-use │ ├─ 匹配成功且 disable-model-invocation != true │ → 自动加载该 skill 并执行 └─ 无匹配 → 普通对话处理2.3 Skill 包内部结构my-skill/ # 目录名建议与 name 一致 ├── SKILL.md # 【必需】YAML frontmatter + Markdown 指令 ├── scripts/ # 【可选】可执行辅助脚本 (py/sh/js…) │ └── validate.py ├── references/ # 【可选】长文档、规范、示例，按需再读 │ └── api-conventions.md └── tests/ # 【可选】脚本单测（复杂 skill 推荐） └── test_validate.py设计原则：组件何时使用加载方式SKILL.mdbody核心流程、决策树触发时注入上下文references/*.md过长规范、少用细节指令中写 “需要时再 read”scripts/*确定性校验、解析、转换通过 shell 调用，路径相对 skill 根3. 目录与发现优先级Grok 按优先级从高到低扫描下列位置。同名 skill高优先级覆盖低优先级。优先级路径模式作用域说明最高./.grok/skills/、./.grok/commands/L