Promote

What This Skill Does

The promote skill graduates proven patterns from Claude's auto-memory into the project's rule system. This turns background notes into enforced instructions. It is useful for developers who want to formalize observed behaviors into project standards.

When to Use

Formalize a project-specific coding style. Enforce the use of specific libraries. Promote a debugging insight to a rule. Standardize error handling approaches. Adopt a preferred architectural pattern.

Key Features

Detects the best target file for the rule. Transforms auto-memory notes into prescriptive rules. Suggests a target based on the scope of the pattern. Distills learnings into concise, one-line rules. Supports project-specific and global rules.

Manual Installation

Manual installationView Full Skill ContentThe complete markdown content that gets installed/si:promote — Graduate Learnings to Rules

Moves a proven pattern from Claude's auto-memory into the project's rule system, where it becomes an enforced instruction rather than a background note.

Usage

/si:promote <pattern description> # Auto-detect best target /si:promote <pattern> --target claude.md # Promote to CLAUDE.md /si:promote <pattern> --target rules/testing.md # Promote to scoped rule /si:promote <pattern> --target rules/api.md --paths "src/api/*/.ts" # Scoped with paths

Workflow

Step 1: Understand the pattern

Parse the user's description. If vague, ask one clarifying question: "What specific behavior should Claude follow?" "Does this apply to all files or specific paths?"

Step 2: Find the pattern in auto-memory

Search MEMORY.md for related entries

MEMORY_DIR="$HOME/.claude/projects/$(pwd | sed 's|/|%2F|g; s|%2F|/|; s|^/||')/memory" grep -ni "<keywords>" "$MEMORY_DIR/MEMORY.md"

Show the matching entries and confirm they're what the user means.

Step 3: Determine the right target

If the user didn't specify a target, recommend one based on scope.

Step 4: Distill into a concise rule

Transform the learning from auto-memory's note format into CLAUDE.md's instruction format:

Before (MEMORY.md — descriptive):

The project uses pnpm workspaces. When I tried npm install it failed. The lock file is pnpm-lock.yaml. Must use pnpm install for dependencies.

After (CLAUDE.md — prescriptive):

Build & Dependencies

Package manager: pnpm (not npm). Use pnpm install.

Rules for distillation: One line per rule when possible Imperative voice ("Use X", "Always Y", "Never Z") Include the command or example, not just the concept No backstory — just the instruction

Step 5: Write to target

For CLAUDE.md: Read existing CLAUDE.md Find the appropriate section (or create one) Append the new rule under the right heading If file would exceed 200 lines, suggest using .claude/rules/ instead

For .claude/rules/: Create the file if it doesn't exist Add YAML frontmatter with paths if scoped Write the rule content

---

paths:

• "src/api/*/.ts"
• "tests/api/*/"

API Development Rules

All endpoints must validate input with Zod schemas Use ApiError class for error responses (not raw Error) Include OpenAPI JSDoc comments on handler functions

Step 6: Clean up auto-memory

After promoting, remove or mark the original entry in MEMORY.md:

Show what will be removed

grep -n "<pattern>" "$MEMORY_DIR/MEMORY.md"

Ask the user to confirm removal. Then edit MEMORY.md to remove the promoted entry. This frees space for new learnings.

Step 7: Confirm

✅ Promoted to {{target}}

Rule: "{{distilled rule}}" Source: MEMORY.md line {{n}} (removed) MEMORY.md: {{lines}}/200 lines remaining

The pattern is now an enforced instruction. Claude will follow it in all future sessions.

Promotion Decision Guide

Promote when:

Pattern appeared 3+ times in auto-memory You corrected Claude about it more than once It's a project convention that any contributor should know It prevents a recurring mistake

Don't promote when:

It's a one-time debugging note (leave in auto-memory) It's session-specific context (session memory handles this) It might change soon (e.g., during a migration) It's already covered by existing rules

CLAUDE.md vs .claude/rules/

Tips

Keep CLAUDE.md under 200 lines — use rules/ for overflow One rule per line is easier to maintain than paragraphs Include the concrete command, not just the concept Review promoted rules quarterly — remove what's no longer relevant/si:promote — Graduate Learnings to Rules

Moves a proven pattern from Claude's auto-memory into the project's rule system, where it becomes an enforced instruction rather than a background note.

Usage

/si:promote <pattern description> # Auto-detect best target /si:promote <pattern> --target claude.md # Promote to CLAUDE.md /si:promote <pattern> --target rules/testing.md # Promote to scoped rule /si:promote <pattern> --target rules/api.md --paths "src/api/*/.ts" # Scoped with paths

Workflow

Step 1: Understand the pattern

Parse the user's description. If vague, ask one clarifying question: "What specific behavior should Claude follow?" "Does this apply to all files or specific paths?"

Step 2: Find the pattern in auto-memory

Search MEMORY.md for related entries

MEMORY_DIR="$HOME/.claude/projects/$(pwd | sed 's|/|%2F|g; s|%2F|/|; s|^/||')/memory" grep -ni "<keywords>" "$MEMORY_DIR/MEMORY.md"

Show the matching entries and confirm they're what the user means.

Step 3: Determine the right target

If the user didn't specify a target, recommend one based on scope.

Step 4: Distill into a concise rule

Transform the learning from auto-memory's note format into CLAUDE.md's instruction format:

Before (MEMORY.md — descriptive):

The project uses pnpm workspaces. When I tried npm install it failed. The lock file is pnpm-lock.yaml. Must use pnpm install for dependencies.

After (CLAUDE.md — prescriptive):

Build & Dependencies

Package manager: pnpm (not npm). Use pnpm install.

Rules for distillation: One line per rule when possible Imperative voice ("Use X", "Always Y", "Never Z") Include the command or example, not just the concept No backstory — just the instruction

Step 5: Write to target

For CLAUDE.md: Read existing CLAUDE.md Find the appropriate section (or create one) Append the new rule under the right heading If file would exceed 200 lines, suggest using .claude/rules/ instead

For .claude/rules/: Create the file if it doesn't exist Add YAML frontmatter with paths if scoped Write the rule content

---

paths:

• "src/api/*/.ts"
• "tests/api/*/"

API Development Rules

All endpoints must validate input with Zod schemas Use ApiError class for error responses (not raw Error) Include OpenAPI JSDoc comments on handler functions

Step 6: Clean up auto-memory

After promoting, remove or mark the original entry in MEMORY.md:

Show what will be removed

grep -n "<pattern>" "$MEMORY_DIR/MEMORY.md"

Ask the user to confirm removal. Then edit MEMORY.md to remove the promoted entry. This frees space for new learnings.

Step 7: Confirm

✅ Promoted to {{target}}

Rule: "{{distilled rule}}" S