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

To create a custom skill for Claude Code, create a new folder under skills/, add a 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.

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 file that serves as both the manifest and the instruction set.

The repository follows a strict contract:

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

mkdir -p skills/my-custom-skill

Write the SKILL.md File

Create the SKILL.md file with the mandatory YAML frontmatter followed by your custom guidelines. The frontmatter must include the name, description, and license fields.

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 and add your skill's relative path to the "skills" array. The path must be relative to the repository root.

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

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

Populate this file with a reference to your 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:

/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, including your custom one. Invoke your skill using the name declared in the 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 with YAML frontmatter (name, description, license) and markdown content embedding the four Karpathy principles.
• Register the path in .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 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, you can create a corresponding file under .cursor/rules/ (using the .mdc extension) that references the same 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.

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