# Debugging Techniques for Incorrect Guideline Application in Karpathy Coding Guidelines

> Fix Karpathy coding guideline errors. Learn to debug plugin config, YAML front matter, and workflow integration issues for smoother development. Improve your application now.

- Repository: [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills)
- Tags: debugging-guide
- Published: 2026-04-19

---

**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`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/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`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/CURSOR.md) according to the *Install* section of the README.

### Guideline Parsing Layer

The **guideline parsing layer** involves the [`SKILL.md`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/SKILL.md) file located at [`skills/karpathy-guidelines/SKILL.md`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/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`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/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`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/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`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/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`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/CLAUDE.md) from the repository’s `main` branch.

2. **Validate the skill file**
   - Open [`skills/karpathy-guidelines/SKILL.md`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/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`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/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`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/SKILL.md) with the upstream version on GitHub ([SKILL.md on main](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/skills/karpathy-guidelines/SKILL.md)).
   - 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.

```text
/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.

```text
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`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/skills/karpathy-guidelines/SKILL.md).

```javascript
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`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/CURSOR.md).
- Validate [`skills/karpathy-guidelines/SKILL.md`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/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`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/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`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/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.