1. 为什么你的 Grok Skill 总是装不上Grok Skill 是 Grok CLI / Grok Build TUI 里的可复用提示词包把一类重复工作流提交规范、PR 审查、部署检查写成SKILL.md让模型按固定流程执行而不是每次会话重新解释一遍。它适合两类人一类是天天在终端里跑 Grok、想把个人习惯固化成斜杠命令的开发者另一类是要把团队操作手册塞进仓库、让所有同事共享同一套流程的工程团队。但真正动手时卡点往往不在写 Markdown而在三件事Skill 放哪个目录才被扫描到、config.toml里[skills]段怎么写、以及怎么确认它真的生效了。我见过太多人把SKILL.md丢进项目根目录然后对着/skills菜单发呆——因为 Grok 只认.grok/skills/、.agents/skills/这类约定路径不会满盘乱找。这篇就按「编写 → 安装 → 部署 → 验证 → 排障」的完整链路走一遍重点给出可直接复制的config.toml配置骨架以及用 TaoToken 统一 Key 打通 API 通道的接入步骤。TaoToken 在这里的角色是统一入口你不需要为每个模型或工具单独维护一套 Key把 base_url 和 Key 配一次Grok CLI 和 Skill 里调用的模型请求都走同一条通道省掉反复切换环境变量的麻烦。先明确一个概念边界Skill 本身不是独立进程它是会话级指令包真正执行依赖 Agent 的工具权限和沙箱策略。所以「安装成功」的判定标准是grok inspect能看到它、/skill-name能跑通而不是某个后台服务在跑。2. 前置准备TaoToken 统一 Key 与目录规划在写第一个 Skill 之前先把两件事定下来API 通道和目录结构。通道决定你的 Skill 里调模型时请求发到哪目录决定 Grok 能不能发现你的 Skill。2.1 TaoToken 统一 Key 的获取与配置TaoToken 的定位是统一 API 通道官网入口在https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 端点是https://taotoken.net/api。你需要先在控制台创建一个 API Key然后把它写进环境变量而不是硬编码进 Skill 文件——Skill 会进 GitKey 不能进 Git。控制台地址https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Keys 管理页https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite拿到 Key 后按操作系统设置环境变量。类 Unixbash/zshexport TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/apiWindows PowerShell$env:TAOTOKEN_API_KEY sk-你的key $env:TAOTOKEN_BASE_URL https://taotoken.net/api想持久化的话类 Unix 写进~/.bashrc或~/.zshrcPowerShell 用[Environment]::SetEnvironmentVariable(TAOTOKEN_API_KEY,sk-你的key,User)。配完开个新终端echo $TAOTOKEN_API_KEY确认能打印出来。注意不要把 Key 写进SKILL.md或config.toml后提交到仓库。Skill 里需要调模型时让脚本从环境变量读取这样团队共享 Skill 时各自用自己的 Key。2.2 目录规划个人 vs 团队Grok 按优先级从高到低扫描 Skill 目录同名 Skill 高优先级覆盖低优先级。核心路径就这几条优先级路径作用域说明最高./.grok/skills/当前工作目录临时调试用高repo/.grok/skills/仓库团队共享建议入库高repo/.agents/skills/仓库与.grok/并列低~/.grok/skills/用户全局个人习惯、实验性 Skill特殊~/.grok/bundled/skills/内置产品自带可被覆盖配置[skills].paths指定自定义共享盘、克隆仓选择逻辑很简单要给队友用就放仓库repo/.grok/skills/name/只给自己用就放~/.grok/skills/name/。有个细节值得记住——.grok/、.agents/、.claude/、.cursor/下的 Skill 不受.gitignore影响只要磁盘上存在就会被加载但文件本身必须真实存在别指望被忽略的目录还能被扫到。3. 可复制配置config.toml 骨架与 SKILL.md 模板这一节是全文最该抄的部分。先给config.toml的[skills]骨架再给SKILL.md的 frontmatter 模板最后给一个带脚本的完整目录示例。3.1 config.toml 的 [skills] 配置骨架编辑~/.grok/config.toml加入以下内容[skills] # 额外扫描目录支持 ~ 展开可以是目录或单个 SKILL.md paths [ ~/my-team-skills, D:/shared/grok-skills, ] # 完全隐藏不出现在 /skills 列表 ignore [~/my-team-skills/wip] # 仍显示但不可用标记为 [disabled] disabled [experimental-deploy] # 兼容层是否扫描 Claude / Cursor 的 skills 目录 [compat.cursor] skills true [compat.claude] skills true三个键的语义要分清paths是追加扫描适合公司内网 Skill 仓或只读网络盘ignore是前缀路径级隐藏整个目录下的 Skill 都不出现disabled是按 Skill 名禁用列表里还能看到但标了[disabled]适合临时关掉某个实验性 Skill 而不删文件。如果不想用兼容层把compat.cursor.skills和compat.claude.skills设为false或者用环境变量GROK_CURSOR_SKILLS_ENABLEDfalse、GROK_CLAUDE_SKILLS_ENABLEDfalse关掉。改完config.toml后视实现可能需要重开会话改完用grok inspect确认。3.2 SKILL.md 的 frontmatter 模板最小可用模板--- name: my-skill description: One-sentence purpose. Use when the user asks for X, Y, or /my-skill. --- # My Skill ## Steps 1. ... 2. ... 3. ...生产级模板带触发场景、参数提示、环境依赖和危险操作保护--- name: deploy-staging description: Deploy the current branch to the staging environment with preflight checks and a post-deploy smoke test. Use when the user wants to deploy to staging, ship a preview, or runs /deploy-staging. Do NOT use for production deploys. when-to-use: deploy staging, ship to staging, preview environment, /deploy-staging argument-hint: [git-ref] compatibility: Requires git, kubectl or your deploy CLI, network access to staging disable-model-invocation: false metadata: short-description: Deploy current branch to staging author: platform-team --- # Deploy Staging ## Usage /deploy-staging [optional-git-ref] Default ref: current HEAD. ## Preconditions 1. Working tree is clean or user explicitly allows dirty deploy 2. Required CLI tools are on PATH (see compatibility) 3. User is on a machine allowed to reach staging ## Steps 1. Resolve target ref (argument or git rev-parse HEAD) 2. Run unit/lint smoke if project scripts exist 3. Show deployment plan; if the environment is shared, confirm with the user 4. Execute deploy command for staging only 5. Run smoke checks (health endpoint / critical path) 6. Report: ref, image/tag, smoke result, links ## Failure Handling - On preflight fail: stop and report; do not deploy - On deploy fail: capture logs; do not roll production - Never target production from this skilldescription是自动调用的命门写法模板是「做什么1–2 句 Use when 场景 A、场景 B或 /skill-name」。太模糊的description: Create git commits几乎不会可靠触发或者乱触发写清能力、规范、触发语和斜杠名才稳。危险操作生产部署、删库、强制推送一定要加disable-model-invocation: true强制只能斜杠手动触发--- name: prod-rollback description: Roll back production to a previous release. ONLY via /prod-rollback. Never auto-invoke. disable-model-invocation: true user-invocable: true argument-hint: release-id --- # Production Rollback ## Hard rules 1. Require explicit release id argument 2. Show blast radius and require user confirmation before any mutating command 3. Prefer standard rollback CLI; no ad-hoc kubectl delete3.3 带脚本的完整目录示例复杂 Skill 推荐把确定性逻辑放脚本长文档放 referencesdeploy-staging/ ├── SKILL.md ├── scripts/ │ └── smoke-check.sh └── references/ └── staging-topology.mdSKILL.md里引用脚本时写相对路径5. Run the smoke script relative to this skill directory if available: bash skill-dir/scripts/smoke-check.sh $BASE_URL脚本里如果需要调模型从环境变量读 TaoToken 的 Key 和 base_url别写死#!/usr/bin/env bash set -euo pipefail BASE_URL${1:?usage: smoke-check.sh base-url} API_KEY${TAOTOKEN_API_KEY:?TAOTOKEN_API_KEY not set} API_BASE${TAOTOKEN_BASE_URL:-https://taotoken.net/api} echo checking ${BASE_URL}/health curl -fsS ${BASE_URL}/health /dev/null echo health OK echo probing model channel via ${API_BASE} curl -fsS ${API_BASE}/models \ -H Authorization: Bearer ${API_KEY} \ | head -c 200 echo4. 安装部署与验证请求写完文件只是第一步装到正确位置并验证生效才算跑通。4.1 三种安装方式个人安装方式 A把 Skill 目录拷到用户全局路径Copy-Item -Recurse .\my-skill $env:USERPROFILE\.grok\skills\my-skill类 Unixmkdir -p ~/.grok/skills cp -r ./my-skill ~/.grok/skills/my-skill团队 Git 部署方式 B推荐目录结构如下然后提交repo/ ├── .grok/ │ └── skills/ │ ├── review-pr/ │ │ └── SKILL.md │ └── deploy-staging/ │ ├── SKILL.md │ └── scripts/ │ └── smoke-check.sh ├── AGENTS.md └── ...git add .grok/skills git commit -m chore: add review-pr and deploy-staging skills git push队友git pull后在仓库内启动 Grok就能用/review-pr、/deploy-staging。配置挂载方式 C适合多仓共用一套 Skill在config.toml的[skills].paths里指向共享目录即可前面骨架已经给过。4.2 验证 Skill 是否生效安装后第一件事是列清单grok inspect人类可读输出会列出 Skill 名和来源。要看机器可读的详细信息含 path、description、userInvocablegrok inspect --json在 JSON 里核对四个字段name、description、source.path、userInvocable以及是否带disabled标记。source的取值含义source含义project / local仓库或当前工作目录user~/.grok/skillsbundled内置提取副本config[skills].paths指定plugin:name插件提供会话内也可以直接查/skills my-skill4.3 端到端跑通一次先手动触发确认 Skill 本体没问题/deploy-staging main再测自然语言自动触发用 2–3 句不同说法试确认不会误触发帮我把当前分支部署到 staging如果 Skill 里带脚本脚本会走 TaoToken 通道发请求。想单独验证通道是否通直接打 APIcurl -fsS https://taotoken.net/api/models \ -H Authorization: Bearer ${TAOTOKEN_API_KEY} \ | head -c 300返回模型列表就说明 Key 和 base_url 都对。想验证具体模型对话是否正常可以到模型对话页手动发一条https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite。如果你是要长期跑编码类 Skill 或 Agent 工作流Coding Plan 更适合按量长期用https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite。热加载方面新增或修改SKILL.md通常数秒内自动生效不用重启改config.toml的[skills]段视实现可能要重开会话装/卸插件在 TUI 里按r重载或重开会话。5. 本篇常见错排查排障的核心工具就两个命令grok inspect和grok inspect --json。下面按现象对照原因。斜杠菜单里没有你的 Skill。先查路径确认SKILL.md真实存在于.grok/skills/name/或~/.grok/skills/name/文件名大小写别写错。再查是否被ignore前缀路径隐藏或者name不符合命名规则2–64 字符、小写字母数字连字符、首尾必须是字母或数字。grok inspect看不到就是没被扫描到。列表里有但自动触发不了。多半是description太泛或者 frontmatter 里写了disable-model-invocation: true。前者改写 description把触发场景和斜杠名写进去后者确认是不是故意禁用了自动调用。调用了错误版本。同名 Skill 多源共存时按优先级覆盖用限定名消解/local:commit指当前目录/user:commit指用户全局/repo:commit指仓库级。grok inspect看来源确认到底加载了哪个。改了文件不生效。极少数缓存或会话问题重开会话同时确认你改的是高优先级路径下的文件别改了低优先级的副本还以为生效了。项目 Skill 队友没有。确认文件已git add并提交且没被误删。注意 Skill 扫描不读.gitignore但文件必须真实存在——被忽略的目录里如果文件在照样加载文件不在怎么配都没用。插件 Skill 不出现。插件未启用或未信任。项目级插件.grok/plugins/需要信任用户级~/.grok/plugins/自动信任。TUI 里/plugins或CtrlL进 Plugins 检查。Claude / Cursor 的 Skill 重复出现。兼容扫描开着关掉compat.cursor.skills或compat.claude.skills或者把重复的加进disabled。脚本执行失败。先确认脚本在目标 OS 上可执行、依赖齐全再确认TAOTOKEN_API_KEY和TAOTOKEN_BASE_URL在当前 shell 里能读到。脚本里用${TAOTOKEN_API_KEY:?...}这种写法Key 没设会直接报错退出比静默失败好排查。6. 把 Skill 接进你的日常链路Skill 写完之后真正让它产生价值的是接入方式。如果你只是偶尔手动跑一下/skill-name就够了但如果你要把 Skill 嵌进编码流程、让 Agent 自动调用那 API 通道的稳定性就是关键。TaoToken 在这里解决的是「统一」问题一个 Key、一个 base_urlGrok CLI 和 Skill 脚本都走同一条通道不用为每个工具单独配环境变量。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite里面有各语言的调用示例和参数说明。Key 管理在https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite建议给不同项目建不同的 Key方便按项目排查用量。如果你用的是 Claude Code 这类工具链Anthropic 兼容接入的说明在https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-code-anthropicutm_campaignrewrite配置方式和本文的config.toml骨架思路一致都是把 base_url 和 Key 配一次后续请求自动走统一通道。最后给一个实操建议先把一个最小 Skill比如/commit从编写到grok inspect验证跑通再往上叠scripts/和references/。我试过一上来就写带三个脚本的部署 Skill结果卡在路径解析上半天回头拆成最小版本反而十分钟就跑通了。Skill 的复杂度应该跟着你的验证节奏走而不是跟着想象走。