GROK BUILD

Skills for the work you repeat

A skill is a saved procedure: a folder with a SKILL.md file. Write one when you correct the same mistake twice. Read any skill you did not write before you rely on it.

Figure 1: A repeated fix becomes a skill, and a later session can apply it when the description matches the task.

1. A skill is a procedure you are tired of retyping

Project rules say how the repository works. A skill says how to do one kind of task. “When you write a commit message, use this shape.” “When you add a masterclass, follow this checklist.” You would otherwise paste that checklist into the chat every time.

On disk a skill is a folder with a SKILL.md file inside it. The file starts with a name and a description, then the steps in ordinary markdown. Grok pulls the skill in when the task matches. It does not load every skill as a wall of text on every turn.

2. Where it lives changes who gets it

A skill in the repository, under .grok/skills/, is for everyone who uses that repository. A skill in your home directory, under ~/.grok/skills/, is for you, on every project. If the same name exists in both places, the project copy wins. A copy in the folder you started in outranks the one at the repository root.

Project skills load after you trust the folder, the same gate as AGENTS.md. There is a /create-skill command if you would rather be walked through the file than create it by hand.

3. The description is the trigger

Grok decides whether a skill applies by reading its description. A vague description means the skill sits there while you do the task by hand. A description that claims to cover everything will show up on tasks it should not touch.

Write the description as the situation, not the slogan. “Use when changing the invoice CSV, its columns, or its test” is a trigger. “Helps you code better” is not. The first lines of the skill should be the steps. Background essays belong somewhere else, or nowhere.

The made-up invoice app could keep this in .grok/skills/invoice-csv/SKILL.md. The description is the whole trigger. The steps are the whole procedure:

---
name: invoice-csv
description: Use when changing the invoice CSV download, its columns, or its test.
---

The columns are Date, Vendor, and Amount, in that order.
Add or update a test in the invoice test file.
Do not change the API.
Run the test command from AGENTS.md, and stop if it fails.

Do not name a skill after a built-in command. A skill named compact does not take over /compact. The built-in keeps that short name, and the skill is only reachable under a longer one.

4. Read a skill before you trust it

A skill is instructions, and those instructions can tell Grok to use tools. That is the point of a good one. It is also why a skill you found, or one left behind by another tool, is not automatically safe.

Grok looks in Claude Code and Cursor skill folders too, unless you turn that compatibility off. If you have used those tools on this machine, their skills may already be visible here. A same-named skill in one of those project folders can outrank the copy in the repository’s .grok/skills. Open the file that will actually run. If you would not type those steps yourself, disable the skill or delete it. “It came with the tool” is not a review.

Layman rule: Unread instructions are still instructions. Read them once, out loud if you have to.

5. Add one when the same correction happens twice

The first time Grok makes a mess, correct it in the chat. The second time it makes the same mess, write the correction into a skill or into AGENTS.md. A skill for a one-off is clutter. A missing skill for a weekly task is how the weekly task keeps going wrong.

After you add one, watch the next real task. If the skill never triggers, fix the description first, not the steps. Long chats are the next failure mode: a long chat goes stale, even when the rules and the skills are right.