How the Plugin System Handles Guideline Updates in the Andrej Karpathy Skills Repository

The plugin system propagates guideline updates automatically by detecting changes in the skill's markdown source files, requiring only an edit to SKILL.md and optionally bumping the version in plugin.json to distribute changes to users.

The multica-ai/andrej-karpathy-skills repository distributes Andrej Karpathy's coding guidelines as a Claude Code plugin. Understanding how the plugin system handles guideline updates is essential for maintainers who need to propagate behavioral changes without complex redeployment workflows.

Understanding the Plugin Architecture

The plugin architecture relies on a declarative manifest and a directory-based skill structure that separates configuration from content.

The Plugin Manifest

At the root of the repository, .claude-plugin/plugin.json serves as the plugin's entry point. This JSON file points to the skill directory ./skills/karpathy-guidelines and optionally tracks the current version. According to the source code, the manifest does not embed the guideline text directly; it only references the location where the content resides.

The Skill Directory Structure

The actual guideline content lives in skills/karpathy-guidelines/SKILL.md. This markdown file contains the authoritative behavioral instructions that Claude Code uses when the plugin is active. The plugin system treats this file as the source of truth, loading its contents dynamically when the plugin initializes.

How Guideline Updates Flow Through the System

The update workflow is file-based and automatic, eliminating the need for code compilation or complex build steps.

Step 1: Edit the Source Markdown

When maintainers need to update guidelines—whether adding a new principle or revising existing wording—they edit skills/karpathy-guidelines/SKILL.md. Changes to ancillary files like CLAUDE.md or .cursor/rules/karpathy-guidelines.mdc also propagate the updated behavior, though SKILL.md remains the primary source.

Step 2: Version Management (Optional)

While not strictly required for the update to function, maintainers can signal a formal release by incrementing the version field in .claude-plugin/plugin.json. This version bump helps the Claude Code marketplace track release history, but the plugin system will serve the latest file contents regardless of whether the version number changes.

Step 3: Marketplace Propagation

Once the edited files are committed to the repository, the Claude Code marketplace automatically detects the changes. The repository remains listed in the marketplace; after commit, new installations automatically receive the updated guidelines.

Step 4: Client Refresh Mechanisms

Existing users receive updates through Claude Code's refresh mechanism. Users can explicitly update the plugin using the CLI commands, or the tool may refresh automatically on restart. When refreshed, Claude Code re-downloads the plugin package, reads the current SKILL.md, and injects the updated guidelines into the assistant's system prompt.

Practical CLI Commands for Guideline Updates

The following commands demonstrate how users interact with the plugin system to receive guideline updates. Note that the specific marketplace path may vary based on the repository fork.

Installing or reinstalling the plugin after a guideline update:

/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills

Forcing a refresh without changing the version:

/plugin update andrej-karpathy-skills

Manually pulling the latest guidelines into a local project:

curl -s https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

Key Files in the Guideline Update Pipeline

Understanding the file structure helps maintainers target the correct locations when propagating changes:

• .claude-plugin/plugin.json – The plugin manifest that references the skill directory and manages version metadata.
• skills/karpathy-guidelines/SKILL.md – The primary source file containing the behavioral guidelines; edits here automatically propagate through the plugin system.
• CLAUDE.md – Project-level fallback file maintained in sync with the skill for repository-specific usage.
• .cursor/rules/karpathy-guidelines.mdc – Cursor IDE rule file that mirrors the skill content for users of the Cursor editor.

Summary

• The plugin system handles guideline updates through file-based detection rather than code compilation, monitoring changes in skills/karpathy-guidelines/SKILL.md.
• Updates propagate automatically when users refresh the plugin or reinstall, with no mandatory version bump required in .claude-plugin/plugin.json.
• The manifest-based architecture separates configuration from content, allowing maintainers to update guidelines by simply editing markdown files.
• Users receive updates through Claude Code CLI commands like /plugin update or automatic refresh on restart.

Frequently Asked Questions

Do I need to bump the version in plugin.json for guideline updates to take effect?

No, version bumps are optional. The plugin system automatically detects changes to SKILL.md and other source files regardless of the version number. However, incrementing the version in .claude-plugin/plugin.json helps track release history and signals formal updates to marketplace users.

How do users receive updated guidelines after I commit changes?

Users receive updates by refreshing the plugin through Claude Code. They can run /plugin update andrej-karpathy-skills to force an immediate refresh, or the plugin may update automatically when Claude Code restarts. The tool re-downloads the package and reads the current SKILL.md to load the new guidelines.

What files should I edit to update the guidelines?

Edit skills/karpathy-guidelines/SKILL.md to change the primary behavioral guidelines. You should also sync changes to CLAUDE.md and .cursor/rules/karpathy-guidelines.mdc to ensure consistency across Claude Code and Cursor IDE environments. The plugin manifest at .claude-plugin/plugin.json only needs editing if you choose to update the version metadata.

Can users manually fetch the latest guidelines without using the plugin system?

Yes, users can manually download the latest guidelines using standard HTTP tools. For example, running curl -s https://raw.githubusercontent.com/multica-ai/andrej-karpathy-skills/main/CLAUDE.md appends the current guidelines directly to their local project file, bypassing the plugin marketplace entirely.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}