# How to Create a Custom Skill for Claude Code Using the Karpathy Guidelines

> Learn to create custom skills for Claude Code following Karpathy guidelines. Add a SKILL.md file, define metadata, write guidelines, and register your skill.

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

---

**To create a custom skill for Claude Code, create a new folder under `skills/`, add a [`SKILL.md`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/SKILL.md) file with YAML frontmatter defining the skill metadata, write your guidelines in the body, and register the path in [`.claude-plugin/plugin.json`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/.claude-plugin/plugin.json).**

The `multica-ai/andrej-karpathy-skills` repository provides a reference architecture for packaging behavioral guidelines as reusable Claude Code skills. When you create a custom skill following this structure, you embed quality gates—such as **Think Before Coding**, **Simplicity First**, **Surgical Changes**, and **Goal-Driven Execution**—directly into your AI-assisted workflow.

## Understanding the Skill Architecture

Claude Code skills are self-contained directories stored under the `skills/` folder. Each skill requires a [`SKILL.md`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/SKILL.md) file that serves as both the manifest and the instruction set.

The repository follows a strict contract:
- **[`SKILL.md`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/SKILL.md)** must contain YAML frontmatter with `name`, `description`, and `license` fields, followed by markdown content that Claude uses as context.
- **[`.claude-plugin/plugin.json`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/.claude-plugin/plugin.json)** acts as the registry, listing relative paths to skill directories that Claude Code should load.
- **`.cursor/rules/`** (optional) contains `.mdc` files that expose the same skills to the Cursor IDE.

The reference implementation in [`skills/karpathy-guidelines/SKILL.md`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/skills/karpathy-guidelines/SKILL.md) demonstrates the required header format and body layout, encoding Andrej Karpathy's principles for reducing common LLM coding mistakes.

## Step-by-Step: How to Create a Custom Skill

### Create the Skill Directory

First, create a dedicated folder for your skill under the `skills/` directory. The folder name should match your skill identifier.

```bash
mkdir -p skills/my-custom-skill

```

### Write the SKILL.md File

Create the [`SKILL.md`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/SKILL.md) file with the mandatory YAML frontmatter followed by your custom guidelines. The frontmatter must include the `name`, `description`, and `license` fields.

```bash
cat > skills/my-custom-skill/SKILL.md <<'EOF'
---
name: my-custom-skill
description: Example skill that demonstrates how to embed Karpathy guidelines in a custom prompt.
license: MIT
---

# My Custom Skill

This skill showcases a simple prompt that asks Claude to generate a one-line summary
of a given text while explicitly following the **Think Before Coding** and **Simplicity First**
principles.

> **Prompt**  
> Summarize the following paragraph in one sentence.  
> Make sure you state any assumptions you make.
EOF

```

The body content should reference the four Karpathy principles—**Think Before Coding**, **Simplicity First**, **Surgical Changes**, and **Goal-Driven Execution**—to ensure your skill inherits the repository's quality guarantees.

### Register the Skill in plugin.json

Open [`.claude-plugin/plugin.json`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/.claude-plugin/plugin.json) and add your skill's relative path to the `"skills"` array. The path must be relative to the repository root.

```json
{
  "name": "andrej-karpathy-skills",
  "description": "Behavioral guidelines to reduce common LLM coding mistakes, derived from Andrej Karpathy's observations on LLM coding pitfalls",
  "version": "1.0.0",
  "author": { "name": "forrestchang" },
  "license": "MIT",
  "keywords": ["guidelines", "best-practices", "coding", "karpathy"],
  "skills": [
    "./skills/karpathy-guidelines",
    "./skills/my-custom-skill"
  ]
}

```

### (Optional) Add Cursor IDE Support

To make your skill available in Cursor, create a rule file under `.cursor/rules/`. Mirror the structure of the existing `karpathy-guidelines.mdc` file.

```bash
touch .cursor/rules/my-custom-skill.mdc

```

Populate this file with a reference to your [`SKILL.md`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/SKILL.md) content so Cursor automatically loads these guidelines when the repository is opened.

## Testing and Using Your Custom Skill

After registering your skill, install or update the plugin in Claude Code:

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

```

Claude Code will load all skill directories listed in [`plugin.json`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/plugin.json), including your custom one. Invoke your skill using the name declared in the [`SKILL.md`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/SKILL.md) frontmatter:

```

/skill my-custom-skill

```

Verify that the output respects the four Karpathy principles—this confirms that your **Goal-Driven Execution** check is working and the skill is behaving as intended.

## Summary

- **Create a directory** under `skills/` with a unique name for your custom skill.
- **Write [`SKILL.md`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/SKILL.md)** with YAML frontmatter (`name`, `description`, `license`) and markdown content embedding the four Karpathy principles.
- **Register the path** in [`.claude-plugin/plugin.json`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/.claude-plugin/plugin.json) so Claude Code discovers the skill.
- **Optionally add** a `.cursor/rules/` file for Cursor IDE compatibility.
- **Test** by installing the plugin and invoking `/skill <your-skill-name>` to verify goal-driven execution.

## Frequently Asked Questions

### What file format must the SKILL.md frontmatter use?

The [`SKILL.md`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/SKILL.md) file must begin with YAML-style frontmatter delimited by triple dashes (`---`). It must include the `name`, `description`, and `license` fields. This format is parsed by Claude Code to register the skill metadata before loading the markdown instructions.

### Can I use the same skill in both Claude Code and Cursor?

Yes. The repository supports dual deployment. After creating your skill under `skills/` and registering it in [`.claude-plugin/plugin.json`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/.claude-plugin/plugin.json), you can create a corresponding file under `.cursor/rules/` (using the `.mdc` extension) that references the same [`SKILL.md`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/SKILL.md) content. This ensures the guidelines load automatically in both environments.

### How do I verify that my custom skill is working correctly?

After installing the plugin in Claude Code using `/plugin install`, invoke your skill with `/skill <your-skill-name>`. Test it with a coding task and verify that the output demonstrates the four Karpathy principles: explicit thinking before coding, preference for simple solutions, surgical rather than wholesale changes, and clear goal-driven execution. If the response follows these constraints, your skill is properly loaded.