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:

```bash
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:

```markdown
## 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

```bash
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