andrej-karpathy-skills

English | 中文

Repository Summary

This repository turns a compact set of Karpathy-inspired coding guidelines into reusable Claude Code assets.

The project exposes the same core guidance through three surfaces:

• CLAUDE.md as a repo-local behavior layer
• skills/karpathy-guidelines/SKILL.md as a Claude Code skill
• .claude-plugin/ metadata as an installable Claude plugin

The central thesis is that a small, sharp behavior contract can counter a recurring class of LLM coding failures: silent assumption-making, overengineering, broad collateral edits, and vague success criteria.

Core Guidance

The repository organizes the guidance into four principles:

1. Think Before Coding

   • make assumptions explicit
   • surface ambiguity instead of silently choosing
   • push back when a simpler path exists
   • stop and ask when confused

2. Simplicity First

   • solve only the requested problem
   • avoid speculative abstractions
   • avoid unnecessary configurability
   • rewrite bloated solutions down to the minimum working shape

3. Surgical Changes

   • touch only lines directly tied to the request
   • avoid opportunistic cleanup of adjacent code
   • match local style instead of imposing a new one
   • clean up only dead code caused by the current change

4. Goal-Driven Execution

   • translate requests into verifiable outcomes
   • prefer tests or explicit checks as success criteria
   • use short plans with per-step verification

Important Repository Surfaces

• README.md: human-facing explanation, install paths, and rationale
• CLAUDE.md: compact reusable behavior layer for project prompts
• skills/karpathy-guidelines/SKILL.md: packaged skill version of the same guidance
• .claude-plugin/plugin.json: plugin metadata for Claude Code distribution
• .claude-plugin/marketplace.json: marketplace metadata
• EXAMPLES.md: example prompt or usage patterns

Why This Source Matters

This repo is not the original Karpathy thread itself. It is a downstream packaging move.

It shows how an operator insight from X can quickly become a reusable distribution artifact for coding agents, spanning:

• per-project instruction files
• reusable skills
• plugin-install surfaces

That makes it relevant as evidence for agent-first repository design and for the distribution story of reusable agent operating models.

Original README Excerpt

The README frames the underlying problem this way:

The models make wrong assumptions on your behalf and just run along with them without checking. They don't manage their confusion, don't seek clarifications, don't surface inconsistencies, don't present tradeoffs, don't push back when they should.

It positions the four principles as a direct behavioral response to those recurring failures.

Local Notes

• This raw file is an editorial source note derived from the repository snapshot on 2026-04-16.
• The repository also contains a more compact skills/karpathy-guidelines/SKILL.md formulation of the same guidance.
• Future maintenance may want a deeper source-family split if more Karpathy-derived packaging repos accumulate.