A Grok CLI skill is a small thing on disk: a folder with a SKILL.md file inside, made of YAML frontmatter and plain markdown instructions. Because it is so small, it is easy to write carelessly. The result is a pack that loads on the wrong turns, never appears as a slash command, or promises a safety boundary it cannot enforce. Treating the file as a contract, where each key states one clear promise, avoids most of that.
Step 1: Name the folder first, then the skill
Pick a kebab-case name such as release-notes or pr-summary and create the folder under ./.grok/skills/ for a single project, or under ~/.grok/skills/ for every project. The name key in the frontmatter must match that parent folder exactly. The open Agent Skills specification requires two keys, name and description, so write those before anything else.
Step 2: Write the description as a trigger, not a summary
The description is what Grok reads when it decides whether to load the pack on its own. A vague line like "helps with docs" pulls the skill into unrelated turns and burns context. A useful description answers two questions in one or two sentences: what the skill does, and when it should fire. For example: "Drafts release notes from merged pull requests. Use when the user asks for a changelog or a release summary." If you need more trigger phrases, put them in when-to-use (when_to_use also works) instead of stuffing the description.
Step 3: Decide who is allowed to start it
There are two separate switches here. user-invocable makes the pack show up as a slash command, such as /release-notes, but only the literal value true counts. Setting disable-model-invocation to true stops Grok from loading the pack automatically, so it stays slash-only. Use both when a skill should run only when a person asks for it, for example anything that touches a shared branch. If two packs share a name, Grok falls back to a qualified form like /local:commit, so short, specific names save you from collisions.
Step 4: Scope it to the files it cares about
The paths key takes gitignore-style globs, and a pack with paths set stays hidden until a matching file is touched. This is a cheap way to keep a migration helper or a docs linter out of sessions where it has nothing to do. argument-hint is worth one line too, since it tells the person typing the slash command what to pass.
Step 5: Know which keys do nothing
Some keys look like controls but are not. Grok accepts model, effort, license, and compatibility, and does not apply them. Extra keys are simply ignored. Most important, allowed-tools does not grant or restrict tools. Writing it down documents your intent, but it is not a permission system.
Step 6: Keep the body short and move bulk out
The markdown body should read like instructions to a careful colleague: the inputs, the steps, the shape of the output, and what to do when something is missing. When the body starts to bloat, move long material into a references/ folder and helper code into a scripts/ folder inside the same skill directory.
Step 7: Verify, then commit
Run grok inspect in the repo you care about, or open /skills in the TUI. Inspect lists the config sources, instruction files, skills, plugins, hooks, and MCP servers it found for that working directory. If your pack is missing, check three things: the directory you launched from, the exact filename SKILL.md, and whether user-invocable is literally true. Once it loads, commit the project folder so teammates inherit the same slash commands.
Where the contract stops
Markdown instructions are not an execution sandbox. A skill can tell the agent to be careful, but it cannot stop a write. If the next step posts to Slack, pushes to GitHub, or edits a CRM record, pair the pack with a two-phase flow: the agent shows a preview of the change first and waits for explicit confirmation before it commits anything.
One note on surfaces. Teach a Task on Grok Bot is a different feature: it records a computer workflow and drafts an account-scoped skill that you still need to harden. SKILL.md packs are git-diffable folders that Grok Build walks on disk, and Grok Build also reads Claude Code skill trees and the AGENTS.md family without extra setup.
If you want the discovery table and every documented frontmatter key in one place, this Grok CLI skills guide lays out how Grok CLI skills are found, invoked, and checked.
Disclosure: the author maintains notes for BotSkillsStack, an independent directory of Grok bot skills that is not affiliated with xAI.