promote

Overview of promote skill

What promote does

The promote skill turns a repeated, proven Claude behavior from auto-memory into an explicit project rule. Instead of leaving a useful pattern buried in MEMORY.md, promote helps move it into CLAUDE.md, .claude/rules/<topic>.md, or a global Claude instruction file so the behavior is enforced consistently in future sessions.

Best fit for self-improving Claude workflows

Use promote when your team already lets Claude learn from corrections, preferences, and repeated project conventions, but now needs one of those learnings to become durable. It is especially useful for Context Engineering setups where MEMORY.md captures observations and rule files define what the agent must reliably follow.

Good examples include “always use pnpm in this repo,” “API handlers must validate input,” or “tests for billing code require these fixtures.” Poor examples are one-off preferences, unresolved debates, or rules you have not seen work in practice.

What makes this promote skill useful

The skill is not just a copy-and-paste reminder. It gives a decision workflow: clarify the pattern, locate supporting memory entries, choose the correct target file, write an enforceable rule, and preserve the original memory with a promotion note. That matters because the hard part is not editing markdown; it is deciding whether a memory deserves permanent enforcement and where that rule belongs.

How to Use promote skill

promote install and repository reading path

Install the skill from the GitHub skill collection with:

npx skills add alirezarezvani/claude-skills --skill promote

Then read SKILL.md first. This repository path currently exposes the promote workflow in a single file, so there are no helper scripts, references, or rule templates to inspect. That makes adoption simple, but it also means you should review the command examples and target-selection table carefully before using it on an important repo.

How to call promote in practice

The intended trigger is /si:promote, followed by the pattern you want to make permanent:

• /si:promote use pnpm instead of npm
• /si:promote API handlers need validation --target rules/api.md
• /si:promote tests for auth changes must include session expiry cases --target rules/testing.md --paths "src/auth/**/*.ts"

The skill first checks what behavior you mean. If your request is vague, it should ask one clarifying question such as whether the rule applies globally or only to certain paths. It then searches the project’s Claude auto-memory file under ~/.claude/projects/.../memory/MEMORY.md for related entries, shows the matches, and confirms that the memory supports the promotion.

Turning a rough goal into a strong prompt

A weak prompt says: “promote our testing preference.” A stronger promote usage prompt gives the behavior, evidence, scope, and target if known:

/si:promote "When changing billing code, add regression tests for failed payment and retry paths" --target rules/testing.md --paths "src/billing/**/*.ts"

This works better because the skill can write an enforceable rule instead of a vague preference. Include:

• the exact behavior Claude should follow
• whether it applies to the whole project, selected file types, or all projects
• example paths if the rule is scoped
• the memory phrase or incident that proved the pattern useful

Suggested workflow before merging the rule

After promote drafts or edits the rule, review it like production configuration. Check that the instruction is short, testable, and not broader than the evidence supports. For project-wide behavior, CLAUDE.md is usually appropriate. For narrow behavior, prefer .claude/rules/<topic>.md with path scope. For a personal convention across repositories, use a global Claude instruction file only if the pattern is truly universal.

promote skill FAQ

Is promote for Context Engineering or general prompting?

Promote is most valuable for Context Engineering because it formalizes the path from observed behavior to persistent instruction. General prompts can ask Claude to remember something for one session; promote helps decide whether that learning should become part of the repo’s operating context.

When should I not use promote?

Do not use promote for untested ideas, temporary workarounds, personal taste that conflicts with team norms, or instructions that belong in application code, tests, linters, or CI. A rule is useful when it guides agent behavior; it is risky when it becomes a substitute for executable enforcement.

How is this different from editing CLAUDE.md manually?

Manual editing can work, but it often skips evidence and scope. The promote skill adds a repeatable process: find the memory, confirm the intended behavior, choose the right destination, and leave a trace that the memory was promoted. That reduces rule sprawl and helps future maintainers understand why the instruction exists.

Is promote beginner friendly?

Yes, if the user already understands where their Claude project memory and rule files live. Beginners should start with a single clear project-wide pattern, use --target claude.md, and avoid scoped path rules until they are comfortable with .claude/rules/ conventions.

How to Improve promote skill

Improve promote results with better evidence

The promote skill performs best when the source memory is specific. Before invoking it, collect the exact memory entry, correction, or repeated failure that proves the rule is needed. “Claude keeps using npm” is weaker than “In three sessions Claude ran npm commands, but this repo uses pnpm and has no package-lock.json.”

Avoid common promotion failures

The most common failure is over-promoting: turning a narrow observation into a global command. Another is writing rules that sound good but are not actionable, such as “write better tests.” A better rule names the trigger, required action, and scope: “For src/api/**/*.ts, validate request bodies before calling service functions.”

Iterate after the first generated rule

After the first promote output, ask whether the rule is too broad, too vague, or duplicated elsewhere. Then refine it. Useful follow-up prompts include:

• “Make this rule enforceable in one paragraph.”
• “Narrow this to only API route files.”
• “Add one example and one non-example.”
• “Check whether this belongs in CLAUDE.md or .claude/rules/testing.md.”

Keep the rule system healthy

A good promote guide should protect the rule layer from becoming noisy. Periodically review promoted rules for conflicts, stale conventions, and instructions that should move into tooling. The best promote outcome is not more markdown; it is fewer repeated corrections because Claude now receives the right durable context at the right scope.