Promote

Promote

Graduate a proven pattern from auto-memory (MEMORY.md) to CLAUDE.md or .claude/rules/ for permanent enforcement

Category: development Source: alirezarezvani/claude-skills

What Is Promote?

The "Promote" skill for Claude is a development utility designed to formalize proven patterns and behaviors, graduating them from ephemeral auto-memory (MEMORY.md) to permanent, enforceable project rules (CLAUDE.md or .claude/rules/). As teams interact with Claude, certain workflows, conventions, or best practices may emerge organically and be captured in MEMORY.md. The Promote skill provides a structured mechanism to elevate these patterns, ensuring they are no longer informal notes but codified instructions that Claude will consistently enforce across a codebase.

Why Use Promote?

In collaborative software projects, consistency and the codification of team knowledge are essential for quality and maintainability. While Claude’s auto-memory is effective for capturing emerging practices, these can become lost or overlooked if not formalized. Promote bridges this gap by allowing teams to:

  • Institutionalize knowledge: Transform transient learnings into persistent, project-wide standards.
  • Reduce ambiguity: By promoting a pattern, you make it explicit, actionable, and enforceable, reducing misunderstandings.
  • Accelerate onboarding: New team members can immediately benefit from a clear set of enforced rules.
  • Automate compliance: Claude will surface and enforce these patterns automatically, reducing manual oversight.
  • Support scoped enforcement: Patterns can be enforced globally or targeted to specific files, modules, or paths.

How to Get Started

The Promote skill is invoked via the /si:promote command. The workflow is designed to be interactive and context-aware, guiding users through the process of elevating a memory pattern to an enforceable rule.

Example Usages

## Promote a general pattern; Claude auto-detects the best target
/si:promote "Always use pnpm for package management."

## Promote a pattern to the global CLAUDE.md ruleset
/si:promote "Review all pull requests for security issues." --target claude.md

## Promote a pattern scoped to testing rules
/si:promote "Unit tests must clean up all resources." --target rules/testing.md

## Promote a pattern scoped to API files only
/si:promote "API handlers require input validation." --target rules/api.md --paths "src/api/**/*.ts"

Workflow Overview

  1. Understand the pattern: Claude parses your description. If the description is vague, Claude prompts for clarification, e.g., "What specific behavior should Claude follow?" or "Does this apply to all files or specific paths?"
  2. Find the pattern in auto-memory: Claude searches MEMORY.md for relevant entries and presents matches for user confirmation.
  3. Determine the right target: Depending on the scope, Claude suggests or applies the correct rule file (CLAUDE.md for global, or .claude/rules/<topic>.md for scoped).
  4. Promote and enforce: The proven pattern is elevated to the specified rules file, making it a permanent instruction for Claude.

Key Features

  • Automatic Target Detection: When a user does not specify a target, Promote intelligently suggests the most appropriate file based on pattern scope.
  • Scoped Promotion: Rules can be global (CLAUDE.md) or granular (e.g., only for API files via .claude/rules/api.md and path filters).
  • Interactive Clarification: If a pattern’s intent or scope is unclear, Promote engages in a brief dialog to refine the rule.
  • Memory Search Integration: Leverages Claude’s MEMORY.md, allowing users to reference and reuse patterns that have already proven effective.
  • Fine-grained Control: Users can specify custom paths, targeting only certain file types or directories for rule enforcement.

Sample Promotion Workflow

Suppose your team consistently sees the benefit of validating input in all API handlers, captured in MEMORY.md as:

All API handlers should validate inputs before processing.

To formalize this, you might run:

/si:promote "API handlers must perform input validation." --target rules/api.md --paths "src/api/**/*.ts"

Claude will search MEMORY.md for related entries, confirm the exact pattern, and promote the rule to .claude/rules/api.md, scoped to files matching src/api/**/*.ts.

Best Practices

  • Be Specific: Provide clear, actionable descriptions when promoting patterns. Vague rules can lead to inconsistent enforcement.
  • Confirm Scope: Always verify whether a rule should be enforced globally or only in certain areas (e.g., only in tests or API logic).
  • Review Promoted Rules: After promotion, review the contents of CLAUDE.md or the relevant rule file to ensure accuracy.
  • Iterative Improvement: Use Promote as part of a continuous improvement workflow, refining rules as your codebase and practices evolve.
  • Avoid Redundancy: Before promoting, check for existing similar rules to prevent duplication.
  • Document Rationale: When possible, add context or reasoning to the rule, aiding future maintainers in understanding its purpose.

Important Notes

  • Irreversibility: Once a pattern is promoted, Claude treats it as a permanent rule; removing or changing it requires manual editing of the rules file.
  • Pattern Matching: For rules targeted to specific paths, ensure your path glob patterns are correct to avoid accidental over- or under-enforcement.
  • User Confirmation: Promote always seeks confirmation before finalizing a rule, minimizing accidental changes.
  • Rule Precedence: In case of conflicting rules (e.g., a global rule and a scoped rule), clarify which should take precedence to avoid ambiguity.
  • Permissions: Ensure you have write access to CLAUDE.md or .claude/rules/ as required by your project’s collaboration settings.

By leveraging the Promote skill, teams can ensure that successful patterns are not only remembered but are actively enforced, driving consistency and quality throughout the development lifecycle.