skill-crafter

Skill Crafter

You produce skills that are immediately useful, auto-discoverable, and follow the exact conventions from the official Grok Build skills guide.

Required Output Format

Every skill you create must contain:

---
name: kebab-case-name
description: >
  One or two sentence description that is specific enough for automatic
  invocation. Include example trigger phrases the user might say.
when-to-use: Optional but recommended — explicit trigger phrases.
argument-hint: "<example usage>"
metadata:
  short-description: "Very short label (optional)"
---

Human Friendly Title

Intro paragraph.

Steps (or Usage / Workflow)

1. Numbered, concrete actions.
2. Each step should mention tools by name when relevant (read_file, grep, spawn_subagent, run_terminal_command, write, etc.).
3. Include success criteria or "what good looks like".

Principles / Important Notes (recommended)

• Anti-hallucination, safety, or verification rules.
• References to other skills or AGENTS.md sections when useful.

## Creation Process

1. Clarify the workflow the skill should capture.
   - Ask for (or infer) the exact trigger phrases users will say.
   - Identify the primary tools the skill will use.

2. Write excellent `description` text.
   - It must be specific. Bad: "Helps with commits". Good: "Create well-formatted git commits following conventional commit standards. Use when the user wants to commit changes or asks for /commit."

3. Structure the body:
   - Start with a short purpose.
   - Use numbered steps (the agent loves ordered procedures).
   - Include verbatim prompts, command examples, or output formats where the skill needs precision.
   - Add "Important Principles" or "Verification" sections for non-trivial skills.

4. Make it self-contained but reference official docs or other skills when relevant (e.g. "follow the todo discipline in AGENTS.md").

5. After writing the file, suggest how the user can test it:
   - `/skills <new-name>`
   - Run a small task that should trigger it automatically.

## Quality Checklist (run this mentally before finishing)

- [ ] Frontmatter has `name` (lowercase, hyphens) and a rich `description`
- [ ] Description contains realistic user phrases that would cause auto-invocation
- [ ] Steps are numbered and reference concrete tool names
- [ ] No vague advice ("be careful") — specific rules instead
- [ ] Under 4000 characters when possible (skills should be focused)
- [ ] Includes at least one realistic example in the body or description

## Scope

- `--project` (default for this repo) → write into `.grok/skills/<name>/`
- `--user` → write into the user's global `~/.grok/skills/<name>/`

This skill was used conceptually while creating the other skills in this repository (`project-auditor`, `readiness-scorer`).

Ship skills that make future Grok sessions dramatically better.