How to Merge Project-Specific Guidelines with Base Karpathy Guidelines

Append the core Karpathy behavioral block from skills/karpathy-guidelines/SKILL.md to your project's CLAUDE.md, then add a dedicated "Project-Specific Guidelines" section for custom rules.

The multica-ai/andrej-karpathy-skills repository provides a canonical set of LLM behavioral guidelines inspired by Andrej Karpathy's coding philosophy. Projects that already maintain their own CLAUDE.md or similar AI instruction files can merge these base guidelines with project-specific rules without creating duplication or conflicts.

Understanding the Base Karpathy Guidelines

The repository defines the core behavioral rules in two primary locations. The skills/karpathy-guidelines/SKILL.md file contains the full canonical text of the Karpathy Guidelines, which serves as the source of truth for merging into project files. Additionally, the .cursor/rules/karpathy-guidelines.mdc file provides a Cursor-specific rule that automatically enforces these guidelines when a project is opened in the Cursor IDE.

According to the repository's README.md (lines 49-63), these guidelines are explicitly designed to be merged with project-specific sections rather than replacing existing documentation.

Step-by-Step Merge Workflow

Follow this workflow to combine the base Karpathy guidelines with your existing project instructions. This approach maintains a clear hierarchy and prevents rule conflicts.

1. Locate or Create Your Project's CLAUDE.md

Identify the file where your project stores LLM-specific instructions. This is typically named CLAUDE.md, but may vary based on your tooling.

2. Copy the Karpathy Block

Copy the entire content from skills/karpathy-guidelines/SKILL.md in the multica-ai/andrej-karpathy-skills repository. This block contains the behavioral guidelines that apply universally.

3. Append and Organize

Paste the Karpathy block into your CLAUDE.md. Place it either at the beginning as foundational context or at the end as reference material. Immediately following the Karpathy block, add a new section titled Project-Specific Guidelines containing only the rules unique to your project.

4. Verify Cursor Integration

If you use Cursor, the .cursor/rules/karpathy-guidelines.mdc file automatically applies when the repository is opened. No additional configuration is required in your merged file for Cursor to recognize the base guidelines.

Code Examples for Merging

Use these commands to programmatically append the Karpathy guidelines to your project documentation.

Appending via Command Line

# From your project root, download and append the base guidelines

curl -sL \
  https://raw.githubusercontent.com/multica-ai/andrej-karpathy-skills/main/skills/karpathy-guidelines/SKILL.md \
  >> CLAUDE.md

# Append your project-specific section

cat <<'EOF' >> CLAUDE.md

## Project-Specific Guidelines

- Use TypeScript strict mode for all new code
- All API endpoints must include unit tests in `tests/`
- Follow the error-handling pattern defined in `src/utils/errors.ts`
EOF

Resulting File Structure

Your final CLAUDE.md should follow this organization:

# Karpathy behavioral guidelines

...(full content from SKILL.md)...

## Project-Specific Guidelines

- Use TypeScript strict mode for all new code
- All API endpoints must include unit tests in `tests/`
- Follow the error-handling pattern defined in `src/utils/errors.ts`

Summary

• Source Location: The base Karpathy guidelines live in skills/karpathy-guidelines/SKILL.md and .cursor/rules/karpathy-guidelines.mdc.
• Merge Method: Append the SKILL.md content to your project's CLAUDE.md, then add a separate "Project-Specific Guidelines" section.
• Tool Integration: Cursor automatically applies the karpathy-guidelines.mdc rule without additional configuration.
• Maintenance: Because both sources are plain Markdown, version controlling the merged file requires only standard git operations.

Frequently Asked Questions

Where are the base Karpathy guidelines stored in the repository?

The canonical guidelines are stored in skills/karpathy-guidelines/SKILL.md as a standard Markdown file. A Cursor-specific version exists at .cursor/rules/karpathy-guidelines.mdc for IDE integration. Both files contain the same core behavioral rules.

Do I need to modify the Cursor settings to use the merged guidelines?

No. Cursor automatically detects and applies the .cursor/rules/karpathy-guidelines.mdc file when you open the repository. You only need to ensure your merged CLAUDE.md is in the project root for Claude to access the project-specific sections.

Can I place the Karpathy guidelines at the end of my CLAUDE.md instead of the beginning?

Yes. The merge workflow supports placing the Karpathy block either before or after your project-specific content. The key requirement is maintaining a clear section hierarchy so the LLM can distinguish between universal guidelines and project-specific rules.

What is the recommended way to keep the merged file updated when the base guidelines change?

Because the base guidelines are plain text in SKILL.md, you can update your merged file by re-downloading the raw content from the multica-ai/andrej-karpathy-skills repository and replacing the Karpathy section in your CLAUDE.md. Using a simple curl command or a git subtree workflow ensures your project stays synchronized with upstream changes.

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