Author a SKILL.md and run it

Why this matters

AGENTS.md is always on. A skill is a procedure you do not want in every prompt: the way this repo cuts a practice-log entry, the way you stage a commit, the way you check a diff before you call the work done. If you keep pasting a 20-line ritual, you do not have a habit. You have a paste buffer.

Specialist rung. If you do not write software or run agents, you can stop after C4 and still have reached repo level.

This module is the last of C1–C6: write a real SKILL.md, put it where Grok discovers it, and run it inside Grok Build. A skill you never invoked is a markdown file. The artifact is the file and a session that followed it.

Teach

What a skill is

A skill is a directory that contains SKILL.md. The markdown body is instructions for a repeatable task. Grok loads a skill when the task matches, or when you invoke it by name.

Use a skill when the procedure is too specific for AGENTS.md and too long to retype. Do not dump your entire house style into a skill. That stays in AGENTS.md.

Where Grok looks

Priority, high to low (deduped by name — higher wins):

Grok also walks .agents/skills/ at each tier and every directory between cwd and repo root. Discovery does not use .gitignore. If the folder is on disk under a known skill root, it loads. To hide one, use [skills] ignore or disabled in ~/.grok/config.toml, not a gitignore line.

Bundled skills live under ~/.grok/bundled/skills/ (including /create-skill). A same-named local, repo, or user skill overrides the bundled copy. grok inspect labels the source: project, user, bundled, config, plugin.

Project scope (<repo>/.grok/skills/<name>/) is what you commit so the team gets it. User scope (~/.grok/skills/<name>/) is personal. Inside a git repo, prefer project.

The file format

---
name: practice-log
description: Append a dated entry to PRACTICE-LOG.md using the repo template. Use when the user wants a practice-log entry, to log a Grok Build session, or asks for /practice-log.
---

# Practice log

## Steps

1. Read PRACTICE-LOG.md and AGENTS.md if they exist.
2. Append today's date heading if missing, then one entry with Task, Accepted, Refused.
3. Show the diff. Do not commit. Do not create a second log file.

Frontmatter:

• name — lowercase, digits, hyphens, up to 64 characters. Spaces and underscores become hyphens. If omitted, the directory name is used.
• description — what it does and when. This is how automatic invocation decides. Vague (“helps with logs”) will not fire. Specific (“Use when the user wants to commit changes or asks for /commit”) will.

Optional fields you may see: when-to-use, allowed-tools, argument-hint, user-invocable (default true), disable-model-invocation (slash only), model, effort, license, compatibility, metadata. You do not need the optional set for this lesson. You do need a sharp description.

If a skill name collides with a built-in (/login, /compact), the built-in keeps the bare name. The skill is still reachable as /local:name, /repo:name, or /user:name. Inspect tags collisions. Rename if you want the bare /name.

Create it

/create-skill in the TUI walks the official flow:

1. Name (2–64, starts and ends with a letter or digit, a-z0-9-)
2. Scope — project (recommended in a git repo) or user
3. What the workflow is
4. A drafted description you approve
5. Writes <scope>/.grok/skills/<name>/SKILL.md (and scripts/ or references/ only if needed)
6. Reads it back and tells you /name

Skills reload from disk within a few seconds. You can also write the directory by hand. Same layout. Do not drop a loose SKILL.md in the repo root and expect it to load.

Run it and verify

/practice-log
/practice-log refused a multi-file rewrite in C4

Arguments after the name go to the skill. / opens the menu; your skill should appear. /skills opens the extensions modal on the Skills tab.

grok inspect

Human output lists name and source. --json includes description, path, userInvocable, and collision fields.

If /name does nothing useful, the body is vague or the description does not match how you speak. Fix the file; do not keep shouting synonyms at the model. Test the slash command before you rely on auto-invoke. Set disable-model-invocation: true if you only want the slash path.

Best practices from the docs, compressed: one skill per workflow; concrete steps; name the tools (read_file, search_replace, run_terminal_command) when the procedure depends on them; commit project skills; do not put secrets in the body.

Worked example

Repo from C4/C5 with PRACTICE-LOG.md and AGENTS.md. In Grok Build:

/create-skill

Name: practice-log. Scope: project. Workflow: append today’s entry to PRACTICE-LOG.md using the existing headings; read the file first; do not commit; do not create another log.

Approve a description that includes the trigger phrases and /practice-log. Let Grok write the files.

Then:

/practice-log C6 authored the skill; accepted the SKILL.md; refused a commit

Watch the scrollback. Grok should read PRACTICE-LOG.md (and maybe AGENTS.md / the skill file), then propose an append. Read the diff. Allow once if it is an append to the log and nothing else.

In a second shell: grok inspect and find practice-log with source project (or local) and a path under .grok/skills/practice-log/SKILL.md.

If /create-skill is not available in your build, create that directory and file yourself, /new, and invoke /practice-log. Same artifact.

Your turn

Do c6-l01-e1 in Grok Build. Author a focused skill, invoke it by slash command, read the diff it proposes, and keep inspect output that shows Grok discovered it. One workflow. No kitchen-sink “do all of Pathway C” skill.

Common failure

File in the wrong place. SKILL.md at the repo root will not load. It has to sit in a skill directory Grok scans.

Description is a slogan. Auto-invoke will never see it. Write the user phrases.

The skill restates AGENTS.md. Cut the overlap. The skill is steps. The rules file is policy.

You allowed a commit because the commit skill example in the docs does that. Your practice skill should not commit unless the whole point is a commit skill, and even then you read git diff --cached first (C4). This lesson’s default practice-log skill does not commit.

Name collides and you think it failed. Try /repo:your-name or rename the directory. Inspect tells you.

What’s next

C7 (later in the pathway) is MCP, plugins, and hooks — how skills and tools grow past what you wrote by hand. C1–C6 is enough to install, stay in ask mode, plan when the approach is the work, accept only the diffs you meant, teach the repo with AGENTS.md, and package a procedure as a skill. That is a working desk. Use it on a real repo this week, still reading every diff.