# forrestchang/andrej-karpathy-skills architecture

> Architecture diagram of the GitHub repository forrestchang/andrej-karpathy-skills, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/forrestchang/andrej-karpathy-skills
- Repository: https://github.com/forrestchang/andrej-karpathy-skills

## Overview

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`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CLAUDE.md) (CLAUDE.md), [`README.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/README.md) (README.md), [`skills/karpathy-guidelines/SKILL.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/skills/karpathy-guidelines/SKILL.md) (SKILL.md), [`.claude-plugin`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/.claude-plugin) (.claude-plugin/)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core content"]
  node_claude_md["CLAUDE.md<br/>canonical guidelines<br/>[CLAUDE.md]"]
end

subgraph group_distribution["Distribution surfaces"]
  node_cursor_md["CURSOR.md<br/>cursor guide<br/>[CURSOR.md]"]
  node_cursor_rule["karpathy-guidelines.mdc<br/>cursor rule"]
  node_skills_dir["skills/<br/>skills package"]
  node_skill_md["SKILL.md<br/>skill definition<br/>[SKILL.md]"]
  node_claude_plugin_dir[".claude-plugin/<br/>plugin package<br/>[.claude-plugin]"]
  node_plugin_json["plugin.json<br/>plugin metadata<br/>[plugin.json]"]
  node_marketplace_json["marketplace.json<br/>marketplace manifest<br/>[marketplace.json]"]
end

subgraph group_docs["Documentation"]
  node_readme["README.md<br/>entry docs<br/>[README.md]"]
  node_readme_zh["README.zh.md<br/>localized docs<br/>[README.zh.md]"]
  node_examples["EXAMPLES.md<br/>usage examples<br/>[EXAMPLES.md]"]
end

node_external_claude(("Claude Code<br/>external consumer"))
node_external_cursor(("Cursor<br/>external consumer"))
node_external_skills(("Skill hosts<br/>external consumer"))
node_external_marketplace(("Marketplace<br/>external consumer"))

node_readme -->|"documents"| node_claude_md
node_readme -->|"documents"| node_cursor_md
node_readme -->|"documents"| node_skill_md
node_readme -->|"documents"| node_claude_plugin_dir
node_readme_zh -.->|"translate"| node_readme
node_examples -->|"illustrates"| node_claude_md
node_claude_md -->|"repackaged as"| node_cursor_rule
node_claude_md -->|"repackaged as"| node_skill_md
node_claude_md -->|"packaged by"| node_plugin_json
node_claude_md -->|"registered by"| node_marketplace_json
node_cursor_md -->|"explains"| node_cursor_rule
node_claude_plugin_dir -->|"contains"| node_plugin_json
node_claude_plugin_dir -->|"contains"| node_marketplace_json
node_skills_dir -->|"contains"| node_skill_md
node_cursor_rule -->|"consumed by"| node_external_cursor
node_claude_md -->|"consumed by"| node_external_claude
node_skill_md -->|"consumed by"| node_external_skills
node_plugin_json -->|"installed via"| node_external_marketplace
node_marketplace_json -->|"published to"| node_external_marketplace

click node_claude_md "https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CLAUDE.md"
click node_readme "https://github.com/forrestchang/andrej-karpathy-skills/blob/main/README.md"
click node_readme_zh "https://github.com/forrestchang/andrej-karpathy-skills/blob/main/README.zh.md"
click node_examples "https://github.com/forrestchang/andrej-karpathy-skills/blob/main/EXAMPLES.md"
click node_cursor_md "https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CURSOR.md"
click node_cursor_rule "https://github.com/forrestchang/andrej-karpathy-skills/blob/main/.cursor/rules/karpathy-guidelines.mdc"
click node_skills_dir "https://github.com/forrestchang/andrej-karpathy-skills/tree/main/skills"
click node_skill_md "https://github.com/forrestchang/andrej-karpathy-skills/blob/main/skills/karpathy-guidelines/SKILL.md"
click node_claude_plugin_dir "https://github.com/forrestchang/andrej-karpathy-skills/blob/main/.claude-plugin"
click node_plugin_json "https://github.com/forrestchang/andrej-karpathy-skills/blob/main/.claude-plugin/plugin.json"
click node_marketplace_json "https://github.com/forrestchang/andrej-karpathy-skills/blob/main/.claude-plugin/marketplace.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_claude_md toneBlue
class node_cursor_md,node_cursor_rule,node_skills_dir,node_skill_md,node_claude_plugin_dir,node_plugin_json,node_marketplace_json toneAmber
class node_readme,node_readme_zh,node_examples toneMint
class node_external_claude,node_external_cursor,node_external_skills,node_external_marketplace toneNeutral
```

## Components

### Core content

Canonical guideline source and its supporting documentation.

- [CLAUDE.md](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CLAUDE.md): canonical guidelines · Primary source of the Karpathy-style instruction set. · `CLAUDE.md`

### Distribution surfaces

Packaged forms of the same guidance for different host tools.

- [CURSOR.md](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CURSOR.md): cursor guide · Explains how to use the Cursor rule in this repo and elsewhere. · `CURSOR.md`
- [karpathy-guidelines.mdc](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/.cursor/rules/karpathy-guidelines.mdc): cursor rule · Committed Cursor rule file for project-level consumption. · `.cursor/rules/karpathy-guidelines.mdc`
- [skills/](https://github.com/forrestchang/andrej-karpathy-skills/tree/main/skills): skills package · Container for reusable skill-based distribution. · `skills`
- [SKILL.md](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/skills/karpathy-guidelines/SKILL.md): skill definition · Skill-form packaging of the same guideline content. · `skills/karpathy-guidelines/SKILL.md`
- [.claude-plugin/](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/.claude-plugin): plugin package · Installable Claude plugin packaging boundary. · `.claude-plugin`
- [plugin.json](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/.claude-plugin/plugin.json): plugin metadata · Plugin metadata for installable distribution. · `.claude-plugin/plugin.json`
- [marketplace.json](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/.claude-plugin/marketplace.json): marketplace manifest · Marketplace-facing distribution manifest. · `.claude-plugin/marketplace.json`

### Documentation

Onboarding and usage docs for the repository and its formats.

- [README.md](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/README.md): entry docs · Main overview, installation paths, and usage guidance. · `README.md`
- [README.zh.md](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/README.zh.md): localized docs · Chinese translation of the main README. · `README.zh.md`
- [EXAMPLES.md](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/EXAMPLES.md): usage examples · Concrete examples that show how the guidance is applied. · `EXAMPLES.md`

### Other components

- **Claude Code**: external consumer · Host environment that consumes CLAUDE.md-style guidance.
- **Cursor**: external consumer · Host environment that loads .mdc project rules.
- **Skill hosts**: external consumer · Agent systems that load modular skills from skills/.
- **Marketplace**: external consumer · Install/registry surface for plugin distribution.

## Connections

- 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.
