How to use the Promote Learnings to Rules agent skill

What is an agent skill and what does promote do?

An agent skill is a folder containing a SKILL.md file that tells an AI agent how to perform a specific task. When a skill matches a request, the agent follows its workflow.

Claude Code can save notes to its auto-memory (MEMORY.md) as it learns how a project works. Those notes are descriptive and stay in the background. The promote skill moves a pattern proven in those notes into the project's rule system, where it becomes an enforced instruction. It searches memory for matching entries, suggests where the rule belongs, rewrites it in imperative form, and removes the original note after you confirm.

Install the promote skill

Download the ZIP from the skill's page on this directory and unzip it into one of the following locations. Use ~/.claude/skills/ to make the skill available across your projects, or a project's .claude/skills/ folder to keep it for that project only.

You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into the project's .claude/skills/ folder
• Claude apps: Settings → Capabilities → Skills, then upload

Check the requirements

The skill needs Claude Code with auto-memory enabled, so that MEMORY.md exists under ~/.claude/projects/. It also needs a Bash-capable shell because it uses grep to search memory, and write access to the project's CLAUDE.md or .claude/rules/ directory.

• Claude Code with auto-memory enabled (MEMORY.md under ~/.claude/projects/)
• A Bash-capable shell for the grep search commands
• Write access to the project's CLAUDE.md or .claude/rules/ directory

Trigger the skill with a command or a natural request

You can run the command directly, for example /si:promote <pattern description>. You can also ask in plain language to make a learned behavior permanent. The skill is designed to activate when you run /si:promote or ask to make a learned behavior permanent.

You can add flags to choose a target. --target claude.md writes to CLAUDE.md, --target rules/testing.md writes to a scoped rule file, and --paths sets the file patterns a scoped rule applies to. Without a target, the skill recommends one based on scope.

• Auto-detect the target: /si:promote <pattern>
• Write to CLAUDE.md: /si:promote <pattern> --target claude.md
• Write to a scoped rule: /si:promote <pattern> --target rules/testing.md
• Scope to paths: /si:promote <pattern> --target rules/api.md --paths "src/api/**/*.ts"

Work through the promotion workflow

The skill asks one clarifying question if your description is vague, then searches MEMORY.md for related entries and shows the matches so you can confirm they are what you mean. It then picks a target by scope: the whole project goes to ./CLAUDE.md, file-type patterns go to .claude/rules/<topic>.md, and personal rules across all projects go to ~/.claude/CLAUDE.md.

The skill turns the descriptive note into an imperative rule with the command included. For example, a note saying npm install failed in a pnpm workspace becomes a single line: use pnpm, not npm, with pnpm install. Before it removes anything, it shows the lines to be removed and asks you to confirm.

• Parse the pattern and ask one question if it is vague
• Search MEMORY.md with grep and confirm the matches
• Choose a target based on scope
• Distill the note into one imperative line that includes the command
• Write the rule, then remove the original entry after you confirm

Review what the skill writes

Because the skill edits project files, read each change before you accept it. The skill warns that if CLAUDE.md would exceed 200 lines, you should move overflow into .claude/rules/. Scoped rule files start with YAML frontmatter that lists paths.

After promoting, the skill reports the target, the distilled rule, the removed MEMORY.md line, and how many lines remain in MEMORY.md out of 200.

• Confirm the target file and section are correct
• Keep CLAUDE.md under 200 lines and move file-specific rules into .claude/rules/
• Check that scoped rules have the right paths in their frontmatter

Safety notes: scripts and network

This skill runs scripts, because it executes grep commands in a shell and edits files in your project and in MEMORY.md. It does not use the network, according to the listing. Since it writes to rule files that Claude follows in every future session, review its edits in version control before you commit them, especially in shared CLAUDE.md files.

Do not promote patterns that may change soon, such as during a migration, because a stale rule can mislead the agent. Also avoid promoting one-off debugging notes or temporary session context, which the skill itself says should stay in memory.

• The skill runs shell commands (grep) and edits files
• No network use is listed for this skill
• Review edits in version control before committing shared rule files

Tips for good promotions

Promote a pattern when it has appeared three or more times in memory, when you have corrected Claude about it more than once, or when it prevents a recurring mistake. Include the concrete command rather than only the concept, and keep one rule per line.

Review promoted rules periodically and remove any that are no longer relevant.

• Promote patterns seen 3+ times or corrected more than once
• Include the exact command, for example pnpm install
• Keep one rule per line
• Put build commands and team conventions in CLAUDE.md; put testing and API rules in .claude/rules/