Skills

Skills are reusable prompt packages that extend Cook with task-specific instructions. They let you capture a repeatable procedure once, instead of re-explaining it each session. Startup discovery skips project skills and commands in untrusted folders.

What Are Skills?

A skill is a directory that contains a SKILL.md file. Its markdown body tells Cook how to handle a specific type of task: step-by-step instructions, conventions, and tool-usage patterns.

Use a skill for a repeatable procedure that's too specific for AGENTS.md but too long to retype. Cook activates a skill only when it applies to your current task.

Skill Locations

Cook discovers skills from these directories, in priority order:

Cook deduplicates skills by name -- a higher-priority location overrides a lower one. Cook also scans .agents/skills/ (and commands/) at each tier (alongside .grok/) and walks every directory between your working directory and the repo root.

Flat *.md files under a commands/ directory become user-invocable slash commands (filename stem = command name), matching Claude Code's legacy custom-command layout.

Skill and command discovery does not use .gitignore. Paths under known skill roots (.grok/, .agents/, .claude/, .cursor/) always load when present on disk — teams often ignore .claude/** as local-only config while still expecting /frontend-style project commands to work. To hide a skill, use [skills] ignore in config (not repo ignore rules).

Cook scans the Claude and Cursor skill directories by default. To stop scanning a vendor, set its skills cell to false under [compat.cursor] or [compat.claude] in ~/.cook/config.toml, or set the GROK_CURSOR_SKILLS_ENABLED or GROK_CLAUDE_SKILLS_ENABLED environment variable to false. See Configuration for details. Cook always filters out known vendor-shipped default skills (such as Cursor's shell, canvas, and statusline), regardless of these settings.

Additional Skill Directories

Manage discovered skills in ~/.cook/skills.toml:

paths = ["~/my-team-skills"]          # Additional directories to scan
ignore = ["~/my-team-skills/wip"]     # Paths to exclude (hidden entirely)
inject = true                       # Include the enabled catalog in the prompt

[status]
bug-fix = true
working-plan = true
wip-skill = false

Each entry in paths is a SKILL.md file or a directory that Cook walks recursively. ignore hides a skill completely; status.<name> = false keeps it listed but excludes it from the system prompt and invocation. paths and ignore take filesystem paths and support ~ expansion; status maps skill names to booleans. Cook records newly discovered skills as true, preserves explicit choices and entries for temporarily missing skills, and migrates the legacy disabled array into false entries. Explicit status takes precedence over legacy settings. inject defaults to true and includes names and descriptions, while full skill content is loaded on invocation.

[paths] extra_skill_dirs is written by /import-claude. It does not inject skills. Put extra directories in paths in ~/.cook/skills.toml.

Creating a Skill

Directory Structure

Each skill lives in its own directory with a SKILL.md file:

~/.cook/skills/
  commit/
    SKILL.md
  review-pr/
    SKILL.md
  deploy/
    SKILL.md

SKILL.md Format

A skill file has YAML frontmatter followed by markdown instructions:

---
name: commit
description: Create well-formatted git commits following conventional commit standards. Use when the user wants to commit changes or asks for /commit.
---

# Git Commit Skill

Review staged changes and create a commit with a clear, conventional message.

## Steps

1. Run `git diff --staged` to see changes
2. Summarize what changed and why
3. Create commit message following conventional commits format
4. Run `git commit -m "..."` with the message

Core Frontmatter Fields

Write a specific description. It determines when Cook invokes the skill automatically. Name the trigger phrases and use cases.

Optional Frontmatter Fields

Multi-word frontmatter keys use kebab-case (single-word keys like model are written as-is).

Creating Skills with /create-skill

The /create-skill command walks you through building a new skill interactively. Cook asks what you want, drafts the files, and writes them to disk.

How It Works

When you run /create-skill, Cook:

1. Gathers requirements. Cook asks for the skill name, the scope to save it under, and a description of the workflow you want to capture. Use a name with lowercase letters, digits, and hyphens (2–64 characters, starting and ending with a letter or digit).

2. Drafts the description. Cook writes a description that states what the skill does, the phrases that trigger it, and the slash command name. You approve or edit the draft before continuing.

3. Creates the skill directory. Cook creates the <scope>/.grok/skills/<name>/ directory, plus scripts/ or references/ subdirectories when the skill needs them.

4. Writes SKILL.md. Cook writes the frontmatter (name and description) and a markdown body of instructions, along with any supporting files.

5. Verifies and confirms. Cook reads the file back, confirms it wrote correctly, and tells you how to run the skill.

Choosing a Scope

Cook asks where to save the skill:

• Project (<repo_root>/.grok/skills/<name>/) -- available only in this repository and shareable with teammates through version control. Cook recommends this scope inside a git repository.
• User (~/.cook/skills/<name>/) -- available across all your projects.

To distribute a skill to a whole team or organization, package it in a plugin and publish it through a marketplace. See Create your own marketplace and Distribute across an organization.

The new skill appears in the slash menu within a few seconds, because Cook reloads skills when files change on disk.

Using Skills

Run a Skill by Name

Each skill is a slash command named after the skill. Run one by typing its name:

/commit              # Runs the "commit" skill
/review-pr           # Runs the "review-pr" skill

Running a skill loads its instructions into the conversation and directs the model to follow them. To pass arguments, type them after the name:

/commit fix the build

To browse your skills, type / to open the slash-command menu. Cook lists every built-in command and skill and filters them as you type. To list skills from the command line instead, run cook inspect (see Viewing Skill Details).

Qualified Names

When a skill's name collides with another skill or a built-in command, Cook keeps both invocable. The built-in keeps the bare name (/login, /compact, …). The skill is advertised under a qualified name prefixed by its scope -- local:, repo:, user:, or the plugin name:

/local:commit        # The "commit" skill from ./.grok/skills/
/user:commit         # The "commit" skill from ~/.cook/skills/
/acme:login          # A plugin skill named "login" (built-in /login is unchanged)

Typing /login in the slash menu shows both rows, with a right-aligned built-in or skill · plugin-name badge so you can tell them apart. Rename the skill (or its directory) if you want the bare /name for the skill instead.

cook inspect tags colliding skills with [collides with /login → /acme:login].

Automatic Invocation

Cook can invoke a skill on its own when it recognizes a relevant task. Cook matches your prompt against the skill's description and when-to-use fields, so write both to describe the triggering situation.

For example, if a skill's description says "Use when the user wants to commit changes," then saying "commit my changes" can trigger that skill automatically. To require an explicit slash command and prevent automatic invocation, set disable-model-invocation: true in the frontmatter.

Viewing Skill Details

Run cook inspect to see every skill Cook discovers, along with the rest of your configuration:

cook inspect          # Human-readable summary
cook inspect --json   # Machine-readable report

In the human-readable output, the Skills section lists each skill's name and its source -- project, user, bundled, config (a [skills].paths entry), server (skills synced from the skill store in managed workspaces), or plugin: <name>. Cook tags any skill disabled via status in ~/.cook/skills.toml or from a disabled vendor surface with [disabled].

The report honors your [skills] config the same way a live session does: skills from paths are listed, skills under an ignore prefix are hidden, and skills with status.<name> = false stay listed but tagged [disabled].

The --json report includes the full detail for each skill: its name, description, source (with the path to the SKILL.md file), and userInvocable flag. Skills whose bare slash name is contested — by a built-in command or by another skill — also include collidesWith (the contested name) and invocableAs (the qualified command to type).

Bundled and Plugin Skills

Cook distributes platform skills separately from your personal skills. Bundled skills are cached under ~/.cook/bundled/skills/; Cook never writes them into ~/.cook/skills/. A same-named local, repo, or user skill overrides the bundled copy. cook inspect labels each definition by its actual source. (A plugin skill of the same name does not override a native skill; it stays available under its qualified plugin:name form.)

Built-in commands keep the bare name against a skill of the same name. /commit and /commit-and-push are built-ins, so a custom commit skill stays available as /user:commit (or /local:commit for a project skill) and both rows appear in the menu.

Skills can also come from plugins. When you install a plugin that includes skills, they appear alongside your user and project skills. cook inspect labels each plugin-provided skill with its source as plugin: <name>.

See the Plugins guide for more on installing plugins that provide skills.

Resetting an edited skill

Editing a skill in Settings → Skills saves your copy to ~/.cook/skills/<name>/SKILL.md, which then overrides the definition Cook ships. That dialog offers a Reset for any skill Cook ships: it writes the shipped SKILL.md back over your copy. The shipped bodies are compiled into the agent from the skills/ tree at build time, so Reset returns the text that build shipped rather than whatever a later bundle sync may have cached under ~/.cook/bundled/skills/.

Reset replaces a copy, so it stays disabled until you have saved one. A skill you wrote yourself ships no default, and the dialog shows no Reset for it. Only SKILL.md is restored; sibling files your copy carries (scripts/, templates/) stay as they are.

Best Practices

1. Write specific descriptions. The description drives automatic invocation. "Create git commits" is too vague; "Create well-formatted git commits following conventional commit standards. Use when the user wants to commit changes or asks for /commit." works better.

2. Include concrete steps. Skills work best when they give Cook a clear, ordered procedure to follow.

3. Reference tools by name. When a skill relies on specific tools (such as run_terminal_cmd or search_replace), name them so the model knows what to use.

4. Keep skills focused. Write one skill per workflow. A "deploy" skill and a "rollback" skill work better than a single "deploy-and-rollback" skill.

5. Version-control project skills. Commit .grok/skills/ to your repository so the whole team benefits. User skills in ~/.cook/skills/ stay personal and unshared.

6. Test by running it. Invoke /name and confirm the skill works before you rely on automatic invocation.

7. Keep the body under the file-read cap. Cook inlines at most the first 25,000 tokens of a skill body (the same cap as read_file). Put long reference material in sibling files and tell Cook to read them with a line offset and limit.