skillmaxxing

Inspired by forrestchang/andrej-karpathy-skills, with practical engineering-loop ideas adapted from mattpocock/skills.

Portable, production-oriented agent operating system for Codex, OpenCode, Claude Code, Cursor, Windsurf, Gemini CLI, Continue, and Aider.

If you have ever watched an agent:

overthink a simple task
rush a dangerous one
polish before validating demand
switch styles mid-task for no reason
or give you no clean way to tell whether it actually worked

this repo is for that.

Works with:

The Problem

Most agent setups fail in the same predictable ways:

They blend incompatible instincts into one vague voice.
They tell the agent to be fast, careful, polished, simple, and innovative at the same time.
They do not separate prototype behavior from production behavior.
They give style guidance, but not a real decision system.
They tell the agent what to do, but not how to know it is working.

That leads to familiar failure modes:

overbuilt MVPs
under-validated launches
unsafe shortcuts in auth, billing, or data paths
endless refactoring before proof
polished output with weak reasoning underneath

The Solution

This repo turns that mess into one coherent operating system:

Layer	What it does	What it fixes
Universal core	Defines rules that never conflict	Stops contradiction
Decision system	Sets strict priority order	Resolves speed vs correctness, polish vs simplicity
Mode packs	Define six distinct execution contracts with first moves, required artifacts, switch signals, and hard no's	Stops personality blending
Routing logic	Chooses the right mode for the current bottleneck	Stops random drift
Operational loops	Standardizes alignment, durable context, TDD, diagnosis, vertical slicing, and architecture deepening	Gives modes concrete engineering habits
Conflict matrix	Makes tradeoffs explicit	Stops hidden contradictions
Example task	Shows the same task across all modes	Makes the system legible fast

The six modes are:

karpathy_mode for first-principles clarity
rauch_mode for UX clarity and product feel
levels_mode for speed to validation and revenue
swyx_mode for AI-native leverage and reusable artifacts
theo_mode for pragmatic production correctness
amjad_mode for agent workflows and environment-driven execution

This is not a personality pack.

It is a phase-aware agent operating system with one active mode at a time.

Who It's Based On

Person	What this system takes from them	Where it shows up
Andrej Karpathy	First-principles reasoning, minimal reference implementations, simplicity under pressure	`karpathy_mode`, core clarity rules
Guillermo Rauch	Product taste, UX clarity, strong defaults, low-config delivery	`rauch_mode`, polish and experience routing
Pieter Levels	Fast shipping, validation-first execution, monetization focus, ruthless scope control	`levels_mode`, MVP and launch behavior
Swyx	AI-native workflow thinking, reusable knowledge artifacts, ecosystem leverage	`swyx_mode`, compounding docs/prompts/evals
Theo Browne	Pragmatic full-stack patterns, strong contracts, boring choices for critical paths	`theo_mode`, production boundaries and risk control
Amjad Masad	Agent workflows, live environments, parallel execution, context-rich tooling	`amjad_mode`, workflow and environment orchestration

The goal is not to imitate their personalities.

The goal is to extract the highest-signal parts of their public builder philosophies and turn them into one coherent routing system.

Why This Repo Is Different

Most prompt repos try to make the agent sound smart.

This one is designed to make the agent behave predictably under changing task phases:

research without getting lost
ship without getting reckless
harden without getting bloated
polish without losing the plot

It is built for the real sequence most builders face:

understand -> validate -> harden -> polish -> scale

How To Know It's Working

This repo is working if you start seeing these changes in behavior:

The agent names the current bottleneck before it starts.
It picks one mode for the current phase instead of blending voices.
It states the mode's first move and what artifact must exist before it can switch.
It states success criteria, not just actions.
It picks a concrete operational loop when the work calls for one.
It explains when it would switch modes and why.
Diffs get smaller and more intentional.
Debugging starts with a reproduction loop before theories.
Large plans become vertical, independently verifiable slices.
MVP tasks stop turning into architecture projects.
Production tasks stop being treated like disposable prototypes.
Conversations become clearer.
Example: We should stay in levels_mode until the offer is validated.
Example: Now the bottleneck is trust, so switch to rauch_mode.
Example: This touches billing, so theo_mode takes over the boundary.

60-Second Test

Open this repo in any supported harness and ask:

Use $agent-skills-system to route this task: build a simple SaaS landing page.

A good result should do four things:

Pick a mode.
Explain why that mode fits the current bottleneck.
Define success criteria.
Tell you when it would switch modes.

Then ask:

Now the page is converting, but it looks untrustworthy. Re-route.

The correct behavior is not "rewrite everything."

The correct behavior is a clean phase transition, usually from levels_mode to rauch_mode.

Across every harness, the working signal is the same:

the agent picks one mode
it names the bottleneck
it defines success criteria
it tells you when it would switch modes
it does not blend all six modes into one vague answer

Quick Start

Use This Repo Directly

Clone it and open the repo in your tool of choice:

git clone https://github.com/your-handle/skillmaxxing.git
cd skillmaxxing

Codex and OpenCode will read AGENTS.md
Cursor and Windsurf can also use AGENTS.md directly
Claude Code will read CLAUDE.md
Gemini CLI will read GEMINI.md and can also discover .agents/skills/agent-skills-system/SKILL.md
Continue will load .continue/rules/agent-skills-system.md
Aider will load .aider.conf.yml and CONVENTIONS.md
Generic skill tooling can start from SKILL.md
The canonical source of truth is agent-skills-system/SKILL.md

Important:

SKILL.md at the repo root is a loader for cloned-source discovery.
For Codex or other user-skill installs, copy the agent-skills-system/ directory, not the entire repo root into a skills folder.
For Codex global installs, use ./scripts/install.sh codex-global so the canonical skill lands in the right place automatically.

Install Into Another Project

Use the installer. For most people, all is the right default:

./scripts/install.sh all /path/to/project

That installs the shared stack:

AGENTS.md for Codex, OpenCode, Cursor, and Windsurf
CLAUDE.md for Claude Code
GEMINI.md plus .agents/skills/agent-skills-system/ for Gemini CLI
.continue/rules/agent-skills-system.md for Continue
.aider.conf.yml plus CONVENTIONS.md for Aider
agent-skills-system/ as the canonical source in the target project

If a target project already has AGENTS.md, CLAUDE.md, or GEMINI.md, the installer appends a managed section only if it is missing. If .aider.conf.yml already exists, the installer leaves it alone and prints the exact read: entries to merge.

Native Per-Tool Install

Use these when you want the harness-native format instead of the shared all setup:

./scripts/install.sh codex-global
./scripts/install.sh codex /path/to/project
./scripts/install.sh opencode /path/to/project
./scripts/install.sh claude /path/to/project
./scripts/install.sh cursor /path/to/project
./scripts/install.sh windsurf /path/to/project
./scripts/install.sh gemini /path/to/project
./scripts/install.sh continue /path/to/project
./scripts/install.sh aider /path/to/project

Native notes:

codex-global installs agent-skills-system/ into ~/.codex/skills/agent-skills-system and moves any previous install to ~/.codex/skill-backups/
cursor writes .cursor/rules/agent-skills-system.mdc
windsurf writes .windsurf/rules/agent-skills-system.md
gemini writes GEMINI.md and .agents/skills/agent-skills-system/
continue writes .continue/rules/agent-skills-system.md
aider writes .aider.conf.yml and CONVENTIONS.md
codex, opencode, and claude write their normal project entrypoints

Manual Install

Codex

./scripts/install.sh codex-global

This installs the canonical skill directory into ~/.codex/skills/agent-skills-system and moves any previous install to ~/.codex/skill-backups/ so Codex does not see two live skill directories.

OpenCode

Project-level install is the safest default, but OpenCode can also use the generic skill format:

mkdir -p .agents/skills
cp -R agent-skills-system .agents/skills/agent-skills-system

Then point your project AGENTS.md at the installed skill.

Claude Code

Project-level install:

cp -R agent-skills-system /path/to/project/agent-skills-system
printf '# Agent Skills System\n\n@agent-skills-system/SKILL.md\n' > /path/to/project/CLAUDE.md

Or import it from a global ~/.claude/CLAUDE.md:

@/absolute/path/to/agent-skills-system/SKILL.md

Cursor

Shared setup:

./scripts/install.sh all /path/to/project

Native rule setup:

./scripts/install.sh cursor /path/to/project

Windsurf