amhuppert/cursor-rules-synchronizer

Cursor Rules Synchronizer

Overview

Synchronizes Cursor Rules to CLAUDE.md, creating a self-contained Rules section that enables Claude Code to discover and apply rules in future sessions.

When to Use

Run this skill when:

• Setting up Cursor Rules in a project for the first time
• After adding new Cursor Rule files
• After modifying existing rule descriptions or organization
• When the Rules section in CLAUDE.md is missing, incomplete, or outdated

Synchronization Workflow

Follow these steps to synchronize Cursor Rules to CLAUDE.md:

Step 1: List Rules

Use the helper command to get all Cursor Rule file paths:

ai skill cursor-rules-synchronizer list

This outputs one file path per line (e.g., .cursor/rules/meta/creating-rules.mdc).

Step 2: Read All Rules

Read each rule file using the Read tool to understand:

• Frontmatter metadata (description, globs, alwaysApply)
• Full rule content
• Purpose and when the rule should be applied

Step 3: Generate Descriptions

For each rule, generate a context-efficient description following the Description Writing Standards below.

Step 4: Update CLAUDE.md

Add or update the Rules section in CLAUDE.md with:

1. Rules Discovery Instructions (if not already present):

   • Explain how to use the Rules section
   • Instruct to review descriptions and read relevant rule files

2. Rules Section:

   • Organize rules by category (extract from directory structure)
   • List each rule with path and generated description

Description Writing Standards

When generating descriptions for CLAUDE.md, follow Claude Skill description best practices:

Format requirements:

• Third person perspective ("This rule should be used when..." not "Use this rule when...")
• Concrete language specifying what the rule does
• Include specific triggers (contexts, file types, tasks)
• Keep under 2 sentences for context efficiency

Adaptation process:

• Use the rule's frontmatter description as starting point
• Read full rule content to understand complete purpose
• Transform into third-person, trigger-rich format
• Prioritize discovery information over implementation details

<example type="valid"> **Input** (from rule): ```yaml description: USE WHEN creating Mermaid diagrams globs: **/*.{md,mdc} ```

Output (for CLAUDE.md): "This rule should be used when creating Mermaid diagrams for AI consumption in markdown or .mdc files. Provides standards for inline comments, self-contained diagrams, and embedded context to eliminate external documentation dependencies." </example>

<example type="invalid"> **Output:** "Use for diagrams."

❌ Not third person, too vague, missing triggers, doesn't specify what rule provides. </example>

CLAUDE.md Structure

The Rules section should follow this structure:

## Project Rules

Review rule descriptions below to identify relevant rules for the current task. Read full rule files when determined to be relevant.

### [category]

- **[path-to-rule]**: [description]
- **[path-to-rule]**: [description]

Helper Command

ai skill cursor-rules-synchronizer list

Lists all Cursor Rule file paths in the project.

Output: One file path per line, suitable for reading with the Read tool.

Context Efficiency Requirements

CLAUDE.md is always loaded into context, so minimize token usage:

• Descriptions under 2 sentences each
• Focus on "what" and "when", not "how"
• Implementation details stay in rule files
• Only essential discovery information in CLAUDE.md