Ultimate Developer Workflow

A unified skill set for AI coding agents combining best practices from the top agent skill repositories:

Source	Stars	Focus
mattpocock/skills	~66k	TDD, debugging, shared language
addyosmani/agent-skills	~35k	Production-grade workflow phases
forrestchang/andrej-karpathy-skills	~120k	Behavioral guidelines
VoltAgent/awesome-design-md	~74k	Design system patterns

Quick Start

Option 1: Copy to Your Project

Copy these files to your project root:

project/
├── .grok/                      # Grok (recommended for this TUI)
│   └── skills/                 # (or symlink the central skills/)
├── .cursor/rules/              # Cursor rules
│   ├── ultimate-dev-workflow.mdc
│   └── ...
├── CLAUDE.md                   # Global agent guidelines (also loaded by Grok)
├── GROK.md                     # Primary for Grok  (new/optimized)
├── AGENTS.md                   # Project conventions & skill mapping
├── CONTEXT.md                  # Domain language glossary (customize per project)
├── docs/adr/                   # Architecture Decision Records
│   └── 0000-template.md
└── references/                 # Quick-reference checklists
    ├── testing-patterns.md
    ├── security-checklist.md
    └── performance-checklist.md

Option 2: Symlink / Central Install (Recommended)

# Symlink for Cursor
ln -s ~/agent-skills/.cursor/rules .cursor/rules

# For Grok: the update script installs everything properly (see below)
# Or manually:
mkdir -p ~/.grok/skills
# then copy or junction the skills/ subfolders

ln -s ~/agent-skills/CLAUDE.md CLAUDE.md
ln -s ~/agent-skills/GROK.md GROK.md
ln -s ~/agent-skills/AGENTS.md AGENTS.md
ln -s ~/agent-skills/references references

Best for Grok: Run update-skills.ps1 (after any edit). It installs:

• GROK.md (and compat files) to ~/.grok/
• All modular skills to ~/.grok/skills/<name>/ → they become /spec-driven-development, /test-driven-development, etc. slash commands and auto-triggerable.

Now any update to this central "Agent Skills" repo can be propagated to all your projects and all your agents (Grok, Cursor, Claude, Gemini).

---

Core Principles

1. Think Before Coding

• State assumptions explicitly
• Present multiple interpretations
• Push back on problematic approaches
• Stop when confused, ask

2. Simplicity First

• No features beyond what was asked
• No premature abstractions
• 100 lines where 1000 would do = failure

3. Surgical Changes

• Touch only what you must
• Don't "improve" orthogonal code
• Clean up only your own mess

4. Verify, Don't Assume

• "Fix the bug" → Write reproduction test first
• "Add validation" → Write tests for invalid inputs
• Multi-step tasks need explicit verification points

---

Development Lifecycle

DEFINE ──→ PLAN ──→ BUILD ──→ VERIFY ──→ REVIEW ──→ SHIP
  │          │         │          │          │          │
  ▼          ▼         ▼          ▼          ▼          ▼
Spec      Tasks     Code       Test       Quality    Deploy

Phase	Skill	One-Liner
Define	grill-with-docs	Refine requirements
Define	spec-driven-development	Write structured spec
Plan	planning-and-task-breakdown	Break into verifiable tasks
Build	incremental-implementation	Build slice by slice
Build	test-driven-development	Red-Green-Refactor
Verify	debugging-and-error-recovery	Reproduce → Hypothesize → Fix
Review	code-review-and-quality	Five-axis quality gates
Ship	git-workflow-and-versioning	Atomic commits
Ship	shipping-and-launch	Pre-launch checklist

---

Skill Mapping

Intent	Skill to Apply
Vague idea	grill-with-docs or start with spec
New project	spec-driven-development
Need tasks	planning-and-task-breakdown
Implementing	test-driven-development (TDD + Prove-It)
Bug fix	debugging-and-error-recovery + Prove-It
UI work	frontend-design + DESIGN.md
Shared language	shared-language
Code review	code-review-and-quality
Master workflow	ultimate-dev-workflow

---

Key Workflows

TDD (Test-Driven Development)

RED:   Write ONE failing test
GREEN: Write minimal code to pass
REFACTOR: Clean up while tests pass

Prove-It (Bug Fixes)

1. Write reproduction test (should FAIL)
2. Implement fix
3. Test PASSES
4. Run full suite

Debugging Loop

1. Reproduce (build fast signal)
2. Hypothesize (3-5 ranked)
3. Instrument (one variable)
4. Fix + regression test
5. Cleanup

---

Five-Axis Code Review

1. Correctness — Matches spec? Edge cases handled?
2. Readability — Can another engineer understand?
3. Architecture — Fits system design?
4. Security — Input validated? Secrets protected?
5. Performance — N+1 patterns? Unbounded ops?

Finding Severity

Prefix	Required?
(none)	Yes
Critical	Yes (blocks merge)
Nit	No
FYI	No

---

File Descriptions

File	Purpose
CLAUDE.md	Global guidelines for all agents
AGENTS.md	Project conventions and skill mapping
CONTEXT.md	Domain language glossary
.cursor/rules/ultimate-dev-workflow.mdc	Cursor rule for development workflow
docs/adr/0000-template.md	Template for Architecture Decision Records

---

Design System (DESIGN.md)

For UI work, create a DESIGN.md file following the Stitch format:

# Design: [Project]

## Visual Theme
Dark-first / Light-first, mood, density

## Colors
- Primary: #hex (role)
- Secondary: #hex (role)

## Typography
- Headings: Font, size, weight
- Body: Font, size, weight

## Components
### Button
- Primary: solid bg, white text
- States: hover, active, disabled

Copy from VoltAgent/awesome-design-md for popular design systems.

---

Common Rationalizations (Ignore These)

"Rationalization"	Reality
"Simple, no spec needed"	Even simple needs acceptance criteria
"I'll write tests after"	You won't
"I know the bug, just fixing it"	30% of obvious fixes are wrong
"It works, good enough"	Working + unreadable + insecure = debt
"I'll clean up later"	Later never comes

---

For Grok Users (This Repo is Optimized for You)

1. After editing any skill or guideline, run .\update-skills.ps1 from this folder.
2. Restart Grok or run grok inspect (or the in-TUI /skills command).
3. In any project, drop GROK.md (or symlink) + rely on ~/.grok/skills/ for the modular ones.
4. Grok will auto-load GROK.md / AGENTS.md / CLAUDE.md as Project Rules and discover the installed skills for both slash commands and automatic intent-based invocation.

The individual skills/<name>/SKILL.md files have been tuned with rich description + when-to-use fields and Grok-specific notes (heavy use of todo_write, run_terminal_command for verification, read_file for loading context, etc.).

Credits

This skill set combines best practices from:

• mattpocock/skills - ~66k stars
• addyosmani/agent-skills - ~35k stars
• forrestchang/andrej-karpathy-skills - ~120k stars
• VoltAgent/awesome-design-md - ~74k stars

---

Last updated: 2026-05 (Grok-optimized edition with native ~/.grok/skills/ support)