Grok Skill Creator

Skill Creator — Grok

Create skills that extend Grok with specialized workflows. Leverages Grok's native subagent spawning, bash, read, write, edit tools.

Three Gates (Pre-flight)

All must pass. If any is no → stop.

1. Grok can't already do this well? → Skill is overhead.
2. User will use it 5+ times? → One-shot → direct prompt.
3. Model has it built-in? → Skill adds complexity, not value.

Skill Anatomy

skill-name/
├── SKILL.md          # Required — frontmatter + instructions
├── scripts/          # Optional — executable code
├── references/       # Optional — loaded on demand
└── assets/           # Optional — templates, icons, fonts

Frontmatter:

name: kebab-case       # Required. Letters, digits, hyphens. Max 64 chars. Verb-led.
description: >         # Required. Triggering conditions + what it does. Slightly "pushy".
  Use when [trigger], [trigger], or [symptom].
paths:                 # Optional. Glob patterns for auto-discovery.
  - "src/**/*.tsx"

Discovery — Grok finds SKILL.md from:

• Project: ./.grok/skills/ (walked up to repo root)
• User: ~/.grok/skills/
• Plugins: any enabled plugin's skills/ directory
• Config: [skills] paths in ~/.grok/config.toml
• Claude Code compat: .claude/skills/, ~/.agents/skills/, AGENTS.md

Invocation: User-invocable skills appear as slash commands /.

The #1 Mistake: Description Trap

When description summarizes the workflow, the model follows the description and skips the body.

# ❌ BAD: Summarizes workflow → model takes shortcut
description: Use for TDD — write test first, watch it fail, write minimal code

# ✅ GOOD: Triggering conditions only → forces model to read the body
description: Use when implementing features or bugfixes, before writing code

Formula: [Action verb] + [value]. Use when [trigger 1], [trigger 2], ... Include 5+ triggers. Add exclusions. Be slightly "pushy" to combat undertriggering.

Creation: 7 Steps

1. Classify Complexity

| Tier | SKILL.md | Dirs | |------|----------|------| | Simple | many mediocre

• ALWAYS/NEVER in caps → yellow flag → reframe with reasoning
• Context window is shared — every token must earn its place
• Keep SKILL.md 100 lines
• No README, CHANGELOG, or extraneous files

Skill types need different structures:

| Type | Focus | Key section | |------|-------|-------------| | Discipline | Rules | Rationalization table + Red Flags | | Technique | How-to | Step-by-step + edge cases | | Pattern | Mental model | When to apply + counter-examples | | Reference | API/docs | Searchable index + retrieval paths |

5. Validate

• YAML valid, name + description present
• Description has 5+ trigger phrases
• No placeholders, referenced paths exist

6. Smoke Test

Spawn 2 subagents — one WITH skill, one WITHOUT. Verify baseline differs. Do NOT tell subagent it's being tested.

7. Iterate

Improve → re-test → repeat until user satisfied or progress stalls.

Evaluation Pipeline

Architecture

Subagents return results in response but may not reliably write to disk. Controller persists all results. Use parallel spawning for eval runs, blocking for graders.

Flow

1. Test cases — 10-20 prompts, 7:2:1 ratio (common/edge/anomalous):

[{"id": 0, "prompt": "user task", "expectations": ["includes X"]}]

2. Paired subagents — spawn WITH + WITHOUT in same turn, batch 2-3 cases:

With-skill:

Execute this task:
- Skill path: 
- Task: 
- Save outputs to: /iter-N/eval-/with_skill/outputs/

Without-skill (baseline): same prompt, no skill path → without_skill/outputs/

3. Persist on notification — immediately write responses to disk. This is the only opportunity to capture timing data.

4. Grade — blocking grader per case:

{"expectations": [{"text": "...", "passed": true, "evidence": "..."}],
 "summary": {"passed": 2, "failed": 1, "total": 3, "pass_rate": 0.67}}

5. Aggregate → benchmark.json + benchmark.md:

| Metric | with_skill | without_skill | Delta |
| Pass rate | 85% ± 5% | 35% ± 8% | +50% |

Use scripts/aggregate_benchmark.py when available.

6. Analyze — non-discriminating (always pass), flaky (high variance), broken (always fail both).

7. Present — show qualitative outputs + quantitative data. For visual review, use eval-viewer/generate_review.py (HTML with Outputs + Benchmark tabs).

Metrics

| Metric | Target | |--------|--------| | Routing accuracy | > 90% | | Output usability | > 80% | | Redundant tokens | `

cd /.. && zip -r .skill / \
  -x "/evals/*" -x "/iteration-*/*" \
  -x "/workspace/*" -x "*__pycache__*" -x "*.DS_Store"

Generate -summary.md: description, when to use, file structure, usage (/), requirements.

5 Common Failures

| # | Failure | Fix | |---|---------|-----| | 1 | Description too vague | 5+ trigger phrases, formula | | 2 | SKILL.md dumping ground (800+ lines) | < 500 lines, split to references/ | | 3 | ALWAYS/NEVER caps | Explain reasoning | | 4 | No smoke test before shipping | Run Step 6 | | 5 | Description summarizes workflow | Triggering conditions ONLY |

Reference Files

• agents/grader.md — assertion evaluation
• agents/comparator.md — blind A/B comparison
• agents/analyzer.md — benchmark analysis
• references/schemas.md — JSON structures (evals, grading, benchmark)
• scripts/aggregate_benchmark.py — benchmark aggregation
• scripts/quick_validate.py — pre-packaging validation

Meta-Advice

1. Description is everything. Great skill + bad description = invisible.
2. Explain why. Model generalizes better with reasoning.
3. Draft then look fresh. First draft: too detailed or too vague.
4. Generalize from feedback. Encode the principle, not the fix.
5. Bundle repeated work. If subagents independently write similar scripts → scripts/.
6. Context window is shared. Every token earns its place.
7. Test before deploying. 15 min testing saves hours debugging.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: taxueseek
• Source: taxueseek/skill-optimizer
• License: MIT

Install and usage instructions live in the source repository linked above.