How forrestchang/andrej-karpathy-skills works
This repository is a prompt/rules distribution package for AI coding assistants, not an application runtime. Its architecture is centered on one core set of guidelines that is repackaged for different host systems: Claude Code, Cursor, and a plugin marketplace.
1. Core content layer
- The main product is a single guideline document: CLAUDE.md.
- It defines the Karpathy-inspired principles: think before coding, simplicity first, surgical changes, and goal-driven execution.
- This file is the canonical source of behavior instructions for Claude Code-style workflows.
2. Distribution surfaces
- The same guidance is exposed through multiple entry points:
- root CLAUDE.md for direct per-project use,
- .cursor/rules/karpathy-guidelines.mdc for Cursor,
- skills/karpathy-guidelines/SKILL.md for skill-based consumption,
- plugin manifests under .claude-plugin/ for installable distribution.
- This is a content-reuse architecture: one guideline set, multiple packaging formats.
3. Claude Code integration
- CLAUDE.md is the primary integration point for Claude Code projects.
- The README treats it as the “single file” users can copy into their own repositories.
- In this repo, it also serves as the source material for the rest of the ecosystem artifacts.
4. Cursor integration
- .cursor/rules/karpathy-guidelines.mdc is a committed project rule for Cursor.
- CURSOR.md explains how to use the rule in this repository and in other projects.
- This makes Cursor a separate consumer boundary, with its own file format and loading mechanism.
5. Claude plugin packaging
- .claude-plugin/plugin.json and .claude-plugin/marketplace.json define plugin metadata and marketplace distribution.
- This layer is what makes the guidelines installable rather than manually copied.
- The plugin acts as a packaging/registry boundary around the same underlying content.
6. Skills subsystem
- skills/karpathy-guidelines/SKILL.md represents the guidance as a reusable skill.
- skills/ is the abstraction layer for agent systems that load skills as modular capabilities.
- The README points to Multica as the broader ecosystem where such skills can be reused and managed.
7. Documentation and onboarding
- README.md is the main entry point and explains the problem, solution, installation paths, and expected behavior changes.
- README.zh.md is the localized Chinese version.
- EXAMPLES.md likely provides concrete usage examples or sample instruction patterns, supporting adoption and correct application.
8. Information flow
- Conceptually, the flow is: guideline principles in CLAUDE.md → repackaged into Cursor rules, skill files, and plugin manifests → consumed by different AI coding tools.
- The repo itself does not execute logic; it ships instructional content into external agent runtimes.
9. Key boundary: content vs. runtime
- There is no application server, build pipeline, database, or API layer.
- The important boundary is between this repository’s static instruction assets and the external assistants that ingest them.
- Architecture diagrams should therefore emphasize packaging/distribution, not service interactions.
10. Authoring and maintenance model
- The repo appears optimized for keeping one coherent guideline set and then mirroring it into the formats required by each host tool.
- That means the main maintenance concern is consistency across CLAUDE.md, Cursor rules, skill markdown, and plugin metadata.
- Any divergence between those files would be an architectural risk because it creates multiple sources of truth.
11. External ecosystem dependency
- The README references the Multica platform and Claude Code plugin installation flow, indicating this repo is intended to plug into external agent-management ecosystems.
- Those external systems are consumers of the packaged guidance, not components of this repository itself.
12. What to draw in a diagram
- Represent the repository as a guideline source repository with one core content node and several distribution adapters.
- Show separate outbound paths to Claude Code, Cursor, and plugin/skill consumers.
- Avoid depicting backend services; the meaningful architecture here is about instruction propagation and packaging.
Main entry points: CLAUDE.md CLAUDE.md · README.md README.md · SKILL.md SKILL.md · .claude-plugin .claude-plugin/
Components 15
Core content
Canonical guideline source and its supporting documentation.
- CLAUDE.md · Primary source of the Karpathy-style instruction set.
CLAUDE.md
Distribution surfaces
Packaged forms of the same guidance for different host tools.
- CURSOR.md · Explains how to use the Cursor rule in this repo and elsewhere.
CURSOR.md - karpathy-guidelines.mdc · Committed Cursor rule file for project-level consumption.
.cursor/rules/karpathy-guidelines.mdc - skills/ · Container for reusable skill-based distribution.
skills - SKILL.md · Skill-form packaging of the same guideline content.
skills/karpathy-guidelines/SKILL.md - .claude-plugin/ · Installable Claude plugin packaging boundary.
.claude-plugin - plugin.json · Plugin metadata for installable distribution.
.claude-plugin/plugin.json - marketplace.json · Marketplace-facing distribution manifest.
.claude-plugin/marketplace.json
Documentation
Onboarding and usage docs for the repository and its formats.
- README.md · Main overview, installation paths, and usage guidance.
README.md - README.zh.md · Chinese translation of the main README.
README.zh.md - EXAMPLES.md · Concrete examples that show how the guidance is applied.
EXAMPLES.md
Other components
- Claude Code · Host environment that consumes CLAUDE.md-style guidance.
- Cursor · Host environment that loads .mdc project rules.
- Skill hosts · Agent systems that load modular skills from skills/.
- Marketplace · Install/registry surface for plugin distribution.
Connections 19
- README.md → CLAUDE.md: documents · README presents CLAUDE.md as the primary single-file artifact.
- README.md → CURSOR.md: documents · README explains Cursor usage and rule loading.
- README.md → SKILL.md: documents · README points to the skill packaging form.
- README.md → .claude-plugin/: documents · README describes plugin installation and distribution.
- README.zh.md → README.md: translate · Localized documentation mirrors the main README.
- EXAMPLES.md → CLAUDE.md: illustrates · Examples demonstrate how the core guidance is applied.
- CLAUDE.md → karpathy-guidelines.mdc: repackaged as · Canonical guidance is mirrored into Cursor rule format.
- CLAUDE.md → SKILL.md: repackaged as · Canonical guidance is packaged as a reusable skill.
- CLAUDE.md → plugin.json: packaged by · Core content is referenced for plugin distribution metadata.
- CLAUDE.md → marketplace.json: registered by · Marketplace manifest exposes the package for installation.
- CURSOR.md → karpathy-guidelines.mdc: explains · Cursor guide explains the committed rule file.
- .claude-plugin/ → plugin.json: contains · Plugin package includes plugin metadata.
- .claude-plugin/ → marketplace.json: contains · Plugin package includes marketplace manifest.
- skills/ → SKILL.md: contains · Skills package contains the reusable skill definition.
- karpathy-guidelines.mdc → Cursor: consumed by · Cursor loads the rule as a project instruction file.
- CLAUDE.md → Claude Code: consumed by · Claude Code consumes the canonical guideline file directly.
- SKILL.md → Skill hosts: consumed by · Skill hosts load the skill definition as a modular capability.
- plugin.json → Marketplace: installed via · Plugin metadata supports installable distribution.
- marketplace.json → Marketplace: published to · Marketplace manifest connects the package to registry distribution.