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, Aider, and Lovable.

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
Compact router	Defines the shared hierarchy and chooses one phase owner	Stops contradiction and mode blending
Progressive mode packs	Loads only the selected execution contract	Protects context from irrelevant guidance
Operational references	Adds verification, security, context, tool, and long-horizon contracts when needed	Turns philosophy into execution behavior
Eval suite	Encodes positive, negative, transition, and risk-sensitive routing cases	Provides a repeatable framework for measuring prompt changes
Deterministic validation	Checks skill structure, references, metadata, fixtures, and installs	Prevents packaging drift
Install lifecycle	Detects stale installs and performs backup-backed updates	Makes improvements safely distributable

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.

Test The Routing

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:

1. Pick a mode.
2. Explain why that mode fits the current bottleneck.
3. Define success criteria.
4. 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

The repository also ships a machine-readable routing suite with positive, negative, transition, security, and long-horizon cases:

python3 scripts/validate.py                    # Validate skill structure and coverage
python3 scripts/evaluate.py --stats            # Show eval coverage statistics
python3 scripts/evaluate.py --references       # List all eval cases
sh tests/evaluate.sh                           # Run eval grader tests
sh tests/install.sh                            # Test installer lifecycle

Current eval coverage: 32 cases total — 25 positive (78%), 7 negative (21%), 4 failure modes (12%), 2 transitions, 7 security-sensitive.

Model-backed runs should use evals/routing.json and the grading contract in evals/rubric.md. For harnesses with structured output support, use the schema in evals/structured-output-schema.json to enable automated evaluation. Run each trial from a fresh session, keep transcripts, and compare pass rate, consistency, time, and token use before accepting a skill change.

Quick Start

Use This Repo Directly

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

git clone https://github.com/johnvouros/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.

Check or update an existing managed install without overwriting unrelated project instructions:

./scripts/install.sh --check all /path/to/project
./scripts/install.sh --update all /path/to/project

--check exits non-zero when a managed directory or template is missing or stale. --update moves replaced managed content into .skillmaxxing-backups/; global Codex backups remain under ~/.codex/skill-backups/.

Lovable

Lovable supports the same SKILL.md convention, but its GitHub importer may reject this repository because the repo contains non-skill assets above Lovable's per-file upload limit. Use the minimal packaged skill instead:

1. Download dist/skillmaxxing-lovable.zip.
2. In Lovable, open Settings → Skills → Add → Upload ZIP.
3. Upload the ZIP, then invoke /agent-skills-system or leave automatic use enabled.

Only workspace owners and admins can import workspace skills. To rebuild the archive after changing the canonical skill, run:

python3 scripts/package_lovable.py

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/
• claude writes the native skill to .claude/skills/agent-skills-system/ without modifying CLAUDE.md
• 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 and opencode 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

For native project-level discovery:

mkdir -p /path/to/project/.claude/skills
cp -R agent-skills-system /path/to/project/.claude/skills/

The installer performs the same setup with lifecycle checks and backup-backed updates:

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

For a shared checkout instead, import the canonical skill from CLAUDE.md without replacing existing project instructions:

@/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

Shared setup:

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

Native rule setup:

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

Gemini CLI

Project memory plus workspace skill:

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

Continue

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

Aider

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

If you already have .aider.conf.yml, merge the printed read: entries instead of replacing your config.

Compatibility Matrix

Tool	Recommended install	Entry file
Codex	codex-global, all, or codex	~/.codex/skills/agent-skills-system or AGENTS.md
OpenCode	all or opencode	AGENTS.md plus .agents/skills/agent-skills-system/
Claude Code	claude or all	.claude/skills/agent-skills-system/ or CLAUDE.md
Cursor	all or cursor	AGENTS.md or .cursor/rules/agent-skills-system.mdc
Windsurf	all or windsurf	AGENTS.md or .windsurf/rules/agent-skills-system.md
Gemini CLI	all or gemini	GEMINI.md plus .agents/skills/agent-skills-system/
Continue	all or continue	.continue/rules/agent-skills-system.md
Aider	all or aider	.aider.conf.yml plus CONVENTIONS.md
Lovable	Upload packaged skill	dist/skillmaxxing-lovable.zip

Suggested Prompts

• Use $agent-skills-system to route this task and pick the right mode.
• Should this task start in karpathy_mode or theo_mode? Explain the switch point.
• Apply the agent skills system and build the smallest complete unit first.
• Use the agent skills system to resolve a speed vs correctness tradeoff.
• Use the agent skills system to diagnose this bug and build the feedback loop first.
• Route this feature and package it into vertical slices with acceptance criteria.
• We have validation but weak UX. Re-route this task using the system.

Repo Layout

.
|-- .aider.conf.yml
|-- .agents/skills/agent-skills-system/SKILL.md
|-- .continue/rules/agent-skills-system.md
|-- AGENTS.md
|-- CHANGELOG.md
|-- CLAUDE.md
|-- CONVENTIONS.md
|-- GEMINI.md
|-- LICENSE
|-- README.md
|-- SKILL.md
|-- agent-skills-system/
|   |-- SKILL.md
|   |-- VERSION
|   |-- agents/openai.yaml
|   `-- references/*.md
|-- evals/
|   |-- routing.json
|   `-- rubric.md
|-- dist/skillmaxxing-lovable.zip
|-- tests/
|   |-- evaluate.sh
|   `-- install.sh
|-- scripts/
|   |-- evaluate.py
|   |-- install.sh
|   |-- package_lovable.py
|   `-- validate.py
|-- templates/
|   |-- cursor/agent-skills-system.mdc
|   `-- windsurf/agent-skills-system.md
`-- .github/workflows/ci.yml

Files

• SKILL.md: repo-root loader for quick discovery and generic tool compatibility. Do not install the repo root as the Codex skill package.
• CHANGELOG.md: conventional record of notable unreleased and released repo changes.
• agent-skills-system/SKILL.md: canonical source of truth.
• agent-skills-system/references/: progressively loaded mode and operational contracts.
• dist/skillmaxxing-lovable.zip: minimal Lovable-compatible workspace skill package.
• evals/routing.json: routing and trigger regression cases.
• evals/structured-output-schema.json: JSON schema for automated routing evaluation.
• scripts/validate.py: deterministic repository validator.
• scripts/evaluate.py: eval grader with coverage statistics and structured output support.
• scripts/package_lovable.py: deterministic builder for the Lovable skill package.
• tests/install.sh: installer lifecycle integration test.
• tests/evaluate.sh: success and failure tests for the structured eval grader.
• docs/SOURCES.md: dated primary sources and evidence-type notes behind the harness update.
• docs/STRUCTURED_OUTPUT.md: documentation for structured routing decision format.
• docs/EXAMPLES.md: concrete implementation examples for MCP servers, verification scripts, and diagnostic tools.
• AGENTS.md: shared project instructions for Codex, OpenCode, Cursor, and Windsurf.
• CLAUDE.md: Claude Code project memory.
• GEMINI.md: Gemini CLI project memory adapter.
• .continue/rules/agent-skills-system.md: Continue always-on rule.
• CONVENTIONS.md: Aider companion instructions.
• .aider.conf.yml: Aider config that loads the conventions and canonical skill.
• .agents/skills/agent-skills-system/SKILL.md: generic workspace skill adapter for OpenCode and Gemini CLI.
• agent-skills-system/agents/openai.yaml: OpenAI skill metadata.
• templates/cursor/agent-skills-system.mdc: Native Cursor rule template.
• templates/windsurf/agent-skills-system.md: Native Windsurf rule template.

License

MIT