Debugging Techniques for Incorrect Guideline Application in Karpathy Coding Guidelines

The most common causes of incorrect guideline application in the Karpathy coding guidelines stem from three layers: plugin configuration errors in .cursor/rules/karpathy-guidelines.mdc, malformed YAML front‑matter in SKILL.md, or incomplete developer workflow integration.

The multica-ai/andrej-karpathy-skills repository provides a compact set of behavioral rules—Think Before Coding, Simplicity First, Surgical Changes, and Goal‑Driven Execution—designed for automatic enforcement by Claude‑Code plugins. When these guidelines fail to trigger, systematic debugging techniques for incorrect guideline application can isolate whether the issue lies in the plugin layer, the parsing layer, or the workflow integration.

Understanding the Three Layers of Guideline Application

Plugin Configuration Layer

The plugin configuration layer is the most common failure point. The rule file .cursor/rules/karpathy-guidelines.mdc must be correctly loaded by the Claude‑Code or Cursor IDE. If the marketplace entry for andrej-karpathy-skills was installed incorrectly, or if the local rule file is missing, the guidelines will not be active.

To diagnose this layer, verify the plugin is listed in Claude’s Installed Plugins UI. Open the rule file in the repository and confirm it is referenced in CURSOR.md according to the Install section of the README.

Guideline Parsing Layer

The guideline parsing layer involves the SKILL.md file located at skills/karpathy-guidelines/SKILL.md. This file contains the YAML front‑matter and the four principle sections. If the markdown was edited in a way that breaks the expected YAML front‑matter or heading structure, the skill parser will skip sections.

To diagnose this layer, open SKILL.md and check that the first three lines contain a valid front‑matter block delimited by ---. Ensure that each principle starts with a level‑2 heading (## 1. Think Before Coding, etc.).

Developer Workflow Layer

The developer workflow layer addresses how the developer integrates the guidelines into their project. If the developer copied only part of the guidelines (e.g., only CLAUDE.md) and omitted the skill definition, Claude has no rule set to enforce.

To diagnose this layer, search the project for name: karpathy-guidelines – it should appear only in SKILL.md. If missing, re‑install the skill via the marketplace command shown in the README.

Step-by-Step Debugging Checklist

Follow this systematic sequence to isolate the root cause of incorrect guideline application.

1. Confirm installation

   • Run the marketplace command from the README (see Install → Option A).
   • If using the raw file, check that curl fetched the current CLAUDE.md from the repository’s main branch.

2. Validate the skill file

   • Open skills/karpathy-guidelines/SKILL.md and look for the YAML header (name: karpathy-guidelines).
   • Verify that the four principle sections exist (## 1. Think Before Coding, etc.).

3. Inspect the rule integration

   • Open .cursor/rules/karpathy-guidelines.mdc (referenced in CURSOR.md).
   • Ensure the rule file imports the skill by name and that the Cursor project loads the .cursor directory.

4. Test a guideline trigger

   • Write a tiny prompt that deliberately violates a principle, e.g., ask the model to "add a generic helper function that is never used".
   • Claude should respond with a warning about Surgical Changes or Simplicity First. If it does not, the skill is not active.

5. Check version consistency

   • Compare the local copy of SKILL.md with the upstream version on GitHub (SKILL.md on main).
   • Update the file if it lags behind; a stale version can miss newer principle definitions.

Practical Code Examples for Debugging

Verifying Plugin Installation in Claude-Code

Use the following commands to confirm the skill is correctly registered in the Claude‑Code environment.

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

If the commands succeed, Claude will list karpathy-guidelines under Installed plugins. Absence from this list indicates a marketplace or network issue.

Testing Guideline Triggers with Minimal Prompts

Create a deliberate violation to force the model to reference the guidelines. This validates that the Surgical Changes principle is active.

Please write a one-line helper that prints "debug" but never gets called.

Expected Claude response (excerpt):

Surgical Changes: The helper function is introduced but never used. Remove it or integrate it where needed.

If Claude provides the code without this warning, the skill is not enforced.

Programmatic Validation of SKILL.md Structure

Use this Node.js script to detect malformed YAML or missing sections in skills/karpathy-guidelines/SKILL.md.

const fs = require('fs');
const path = './skills/karpathy-guidelines/SKILL.md';
const content = fs.readFileSync(path, 'utf8');

if (!content.startsWith('---')) {
  console.error('Missing YAML front-matter');
}
if (!/##\s+1\.\s+Think Before Coding/.test(content)) {
  console.error('Think Before Coding section not found');
}

Running this script flags structural problems that prevent the skill parser from loading the guidelines, allowing you to correct formatting before re-deployment.

Summary

• Debugging techniques for incorrect guideline application require investigating three distinct layers: plugin configuration, guideline parsing, and developer workflow.
• Verify installation by checking the Claude‑Code plugin list and confirming the .cursor/rules/karpathy-guidelines.mdc file is referenced in CURSOR.md.
• Validate skills/karpathy-guidelines/SKILL.md for intact YAML front‑matter and correct ## heading structure for all four principles.
• Test enforcement by submitting prompts that deliberately violate Surgical Changes or Simplicity First and confirming the model responds with guideline warnings.
• Use programmatic checks (Node.js, curl, or manual inspection) to ensure version consistency with the upstream multica-ai/andrej-karpathy-skills repository.

Frequently Asked Questions

Why is the karpathy-guidelines skill not appearing in my Claude-Code plugins?

The skill fails to appear when the marketplace command was not executed or the network request failed. Run /plugin marketplace add forrestchang/andrej-karpathy-skills followed by /plugin install andrej-karpathy-skills@karpathy-skills. If the issue persists, verify that your Claude‑Code client is updated to a version that supports the marketplace protocol.

How do I know if SKILL.md is properly parsed by the skill system?

Open skills/karpathy-guidelines/SKILL.md and confirm the file starts with a YAML front‑matter block enclosed by --- on the first and third lines. Check that each of the four principles begins with a level‑two heading (##). If the parser rejects the file, Claude will not display guideline warnings during code generation.

What should I do if Claude ignores the Surgical Changes principle?

First, confirm the skill is active by submitting a test prompt that introduces an unused helper function. If Claude generates the code without flagging it as a violation of Surgical Changes, inspect .cursor/rules/karpathy-guidelines.mdc to ensure it correctly imports the skill. Re‑install the skill from the marketplace if the rule file is missing or stale.

Can I use these debugging techniques for other Claude-Code skills?

Yes, the layered approach applies universally to Claude‑Code skill debugging. Any skill that relies on YAML front‑matter in a SKILL.md file and a corresponding rule file in .cursor/rules/ can be validated using the same checklist: verify installation, validate front‑matter structure, inspect rule integration, and test with deliberate violations.

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