# karpathy-guidelines

Adopt this skill: https://proskills.md/skills/other/vincent-a-yang-karpathy-skills-anycoding-skills-karpathy-guidelines

Page: https://proskills.md/skills/other/vincent-a-yang-karpathy-skills-anycoding-skills-karpathy-guidelines
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/karpathy-guidelines/SKILL.md
size: 2027
sha: 68c132d90faaff5047f5cbb598e759a16549af7e
upstream: https://github.com/vincent-a-yang/karpathy-skills-anycoding/blob/anycoding/skills/karpathy-guidelines/SKILL.md

````text
---
name: karpathy-guidelines
description: Tool-agnostic behavioral guidelines for AI coding assistants. Use when writing, reviewing, debugging, or refactoring code to reduce overengineering, surface ambiguity, make surgical changes, and define verifiable success criteria.
license: MIT
tags:
  - ai-coding-assistant
  - coding-agent
  - prompt-engineering
  - software-engineering
  - opencode
  - trae
  - openclaw
  - claude-code
  - cursor
---

# Karpathy Guidelines

This reusable skill packages a portable behavioral policy for coding agents.

It is inspired by Andrej Karpathy's comments on common LLM coding failure modes and adapted for broad tool compatibility.

## 1. Think Before Coding

Do not assume. Do not hide confusion. Surface tradeoffs.

- State assumptions explicitly.
- Ask when the task is materially ambiguous.
- Present multiple interpretations when they matter.
- Push toward simpler solutions when appropriate.

## 2. Simplicity First

Write the minimum code that solves the requested problem.

- No unrequested features.
- No speculative abstractions.
- No fake flexibility.
- No unnecessary complexity.

If a senior engineer would call it bloated, simplify it.

## 3. Surgical Changes

Touch only what you must.

- Do not refactor unrelated code.
- Do not rewrite nearby formatting or comments without reason.
- Match the local code style.
- Only clean up code made obsolete by your own change.

Every changed line should connect directly to the task.

## 4. Goal-Driven Execution

Define success criteria and verify them.

- Reproduce bugs before fixing them when feasible.
- Prefer tests or direct checks over vague confidence.
- Use a short plan for multi-step work.

Example:

```text
1. reproduce issue -> verify: failing test or failing check
2. implement minimal fix -> verify: issue no longer reproduces
3. run regression checks -> verify: related behavior still passes
```

## Usage

Merge this skill with repository-specific instructions, framework conventions, and testing requirements.
````

## File: README.md
upstream: https://github.com/vincent-a-yang/karpathy-skills-anycoding/blob/anycoding/README.md

````text
# karpathy-skills-anycoding

Universal, reusable coding-agent skills for OpenCode, Claude Code, Cursor, Trae, OpenClaw, and other AI coding tools.

[English](./README.md) | [简体中文](./README.zh.md)

## Install behavior, not boilerplate

Most AI coding tools can write code.

Far fewer can consistently:

- stop and ask when requirements are ambiguous
- choose the smallest correct implementation
- avoid unrelated edits
- define success criteria before changing code

This project gives coding agents a compact behavior layer that improves those habits across tools.

## What this is

`karpathy-skills-anycoding` is a tool-agnostic skill pack that helps AI coding assistants behave more like pragmatic senior engineers.

It turns a small set of high-signal engineering behaviors into reusable instruction files, adapters, and install scripts that work across multiple coding-agent tools.

## Why this is different from a random prompt

This repository is designed to be:

- portable across multiple AI coding tools
- short enough to stay influential
- practical enough for real repositories
- explicit about compatibility instead of overclaiming support

It is not a giant framework prompt. It is a small operating layer for coding behavior.

## Why people use it

Many coding agents still tend to:

- make silent assumptions
- overengineer solutions
- edit unrelated code
- start coding before defining success criteria

This repository pushes them toward the opposite behavior:

- clarify ambiguity first
- prefer the smallest correct solution
- make surgical diffs
- verify outcomes against concrete checks

## The four principles

1. Think Before Coding
2. Simplicity First
3. Surgical Changes
4. Goal-Driven Execution

These principles are inspired by Andrej Karpathy's public comments about common LLM coding failure modes.

## Install in one command

Use the installer that matches your tool and run it inside the repository where you want the rules to apply.

If your tool supports project instructions, rules files, custom skills, or system prompts, this project gives you a ready-to-install starting point.

By default, the installer writes into your current working directory. For OpenCode, that means you should usually run it from your project root so it creates `./AGENTS.md` for that project.

### OpenCode

```bash
curl -fsSL https://raw.githubusercontent.com/Vincent-A-Yang/karpathy-skills-anycoding/anycoding/scripts/install.sh | bash -s -- --tool opencode
```

### Claude Code

```bash
curl -fsSL https://raw.githubusercontent.com/Vincent-A-Yang/karpathy-skills-anycoding/anycoding/scripts/install.sh | bash -s -- --tool claude
```

### Cursor

```bash
curl -fsSL https://raw.githubusercontent.com/Vincent-A-Yang/karpathy-skills-anycoding/anycoding/scripts/install.sh | bash -s -- --tool cursor
```

### Universal install

```bash
curl -fsSL https://raw.githubusercontent.com/Vincent-A-Yang/karpathy-skills-anycoding/anycoding/scripts/install.sh | bash -s -- --tool universal --output AGENTS.md
```

### PowerShell

```powershell
irm https://raw.githubusercontent.com/Vincent-A-Yang/karpathy-skills-anycoding/anycoding/scripts/install.ps1 | iex
Install-KarpathySkills -Tool claude
```

### What the installer does

- `opencode` appends a marked block into `AGENTS.md`
- `claude` appends a marked block into `CLAUDE.md`
- `cursor` writes `.cursor/rules/karpathy-guidelines.mdc`
- `universal` appends a portable block into a target file such as `AGENTS.md`

If the block already exists, the installer skips duplicate insertion.

### OpenCode project vs global install

For OpenCode, there are two useful locations:

- Project-specific rules: `./AGENTS.md` in the project root
- Global personal rules: `~/.config/opencode/AGENTS.md`

Recommended default: install into the project root.

If you want global personal behavior across all OpenCode sessions, you can either copy the generated file manually:

```bash
cp AGENTS.md ~/.config/opencode/AGENTS.md
```

or install directly to the global path:

```bash
curl -fsSL https://raw.githubusercontent.com/Vincent-A-Yang/karpathy-skills-anycoding/anycoding/scripts/install.sh | bash -s -- --tool opencode --output ~/.config/opencode/AGENTS.md
```

## Supported tools

### Confirmed direct instruction surfaces

These have known file or rule entry points and should work directly when installed to the expected path:

- OpenCode via project-root `AGENTS.md`
- Claude Code via project-root `CLAUDE.md`
- Cursor via `.cursor/rules/karpathy-guidelines.mdc`

### Portable adapter templates

These adapters are included as ready-to-use templates, but exact auto-loading behavior depends on the tool version and configuration model:

- Trae
- OpenClaw
- other prompt-driven or rules-driven coding agents

## Common use cases

- make an AI coding assistant stop overengineering routine changes
- reduce drive-by refactors in generated diffs
- add a reusable behavior layer across multiple tools in one team
- improve project instruction quality without writing a long custom system prompt
- bootstrap better coding habits for a new agent-enabled repository

## Quick start

### Option 1: use the core skill

Copy `core/karpathy-anycoding.md` into your tool's instruction surface.

### Option 2: use a ready-made adapter

Pick the closest file from `adapters/` and place it where your tool expects project instructions.

### Option 3: use the reusable skill package

If your tool supports a `SKILL.md`-style reusable package, use `skills/karpathy-guidelines/SKILL.md`.

## What success looks like

You know the skill is working when you start seeing:

- more clarifying questions before implementation
- smaller diffs with fewer unrelated edits
- simpler code on the first pass
- more explicit verification and fewer vague completions

## Repository structure

```text
karpathy-skills-anycoding/
├── README.md
├── README.zh.md
├── LICENSE
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── .gitignore
├── core/
│   └── karpathy-anycoding.md
├── scripts/
│   ├── install.sh
│   └── install.ps1
├── skills/
│   └── karpathy-guidelines/
│       └── SKILL.md
├── adapters/
│   ├── claude/
│   │   └── CLAUDE.md
│   ├── cursor/
│   │   └── .cursor/
│   │       └── rules/
│   │           └── karpathy-guidelines.mdc
│   ├── opencode/
│   │   └── AGENTS.md
│   ├── openclaw/
│   │   └── AGENTS.md
│   ├── trae/
│   │   └── AGENTS.md
│   └── universal/
│       └── SYSTEM_PROMPT.md
└── docs/
    ├── ADOPTION.md
    ├── COMPATIBILITY.md
    └── GITHUB_METADATA.md
```

## Recommended setup by tool

### OpenCode

Use the installer or copy `adapters/opencode/AGENTS.md` to your project root as `AGENTS.md`.

For global personal defaults in OpenCode, place the same content at `~/.config/opencode/AGENTS.md`.

### Claude Code

Use the installer or copy `adapters/claude/CLAUDE.md` to your project root as `CLAUDE.md`.

### Cursor

Use the installer or place `adapters/cursor/.cursor/rules/karpathy-guidelines.mdc` in `.cursor/rules/`.

### Trae

Start from `adapters/trae/AGENTS.md`, then place it into Trae's workspace instruction or agent profile surface.

### OpenClaw

Start from `adapters/openclaw/AGENTS.md`, then place it into the tool's project instruction or bootstrap prompt surface.

### Other AI coding assistants

Start from `adapters/universal/SYSTEM_PROMPT.md` or `core/karpathy-anycoding.md`.

## Why this approach works

This project focuses on behavioral instructions, not tool-private plugin logic.

That makes it portable across tools that support any of the following:

- project instructions
- rules files
- custom skills
- system prompts
- workspace memory
- agent profiles

It works best when combined with repository-specific engineering rules such as language conventions, testing requirements, framework patterns, and security constraints.

## FAQ

### Is this tied to one AI tool?

No. The core is tool-agnostic. Some adapters target known file-based entry points, while others are portable templates.

### Does this
````
