meta-promote

When to Use This Skill

Use this skill when...	Use a different skill when...
Two or more sibling `.claude/` scopes hold rules/skills/commands with the same name or topic, and you want to decide whether to lift them up to a shared parent	You want to copy a project's config into your user-global config (use `meta-assimilate`)
A portfolio root (e.g. `~/repos/`) has children whose configs overlap and you want to promote the common kernel	You want to review existing agent configs for security and frontmatter completeness without changing scopes (use `meta-audit`)
You suspect a rule is duplicated across sibling repos and want a structured promotion / extraction / keep-scoped decision per file	You want to author a brand-new skill from scratch (use `custom-agent-definitions`)

Context

Current directory: !pwd
Local .claude/ tree: !find . -path '*/.claude/*' -maxdepth 4 -type f -name '*.md' -not -path '*/node_modules/*' -not -path '*/.claude/worktrees/*'
Child .claude/ trees (one level down): !find . -mindepth 2 -maxdepth 4 -type d -name '.claude' -not -path '*/node_modules/*'

Parameters

Parse $ARGUMENTS:

scope-path (optional, default .) — the directory whose children's .claude/ trees should be evaluated for promotion up to this directory. The skill always treats scope-path as the target scope and its immediate .claude/-bearing children as the source scopes.

Your task

Execute this evaluation and (with approval) apply it. Do not promote anything without explicit per-candidate confirmation — promotion is a write to shared state and easy to get wrong.

1. Build the scope inventory

Walk three layers:

Layer	Path	Role
Target	`<scope-path>/.claude/{rules,skills,commands,agents}/`	Where promoted files would land
Sources	`<scope-path>/*/.claude/{rules,skills,commands,agents}/`	Children whose contents are candidates
Upstream	User-global `.claude/rules/` (resolve `$HOME/.claude/rules` during execution, not in the Context block) and any plugin skills already loaded for this session	Already-covered material — promotion to the target would just duplicate this

For the upstream layer, run Glob(pattern="$HOME/.claude/rules/**/*.md") during execution and read filenames + first heading of each match. The plugin-skill list is already in the session prompt — scan it for relevant entries by name.

For each source file, record (scope, kind, name, path) where kind ∈ {rule, skill, command, agent} and name is the filename or skill directory name.

2. Find overlap candidates

Group source files by (kind, name). Three kinds of overlap matter:

Same-name across sources — the same filename appears in two or more sibling scopes (e.g. ci-cd-workflows.md in both OrgA/.claude/rules/ and OrgB/.claude/rules/)
Same-topic across sources — different filenames, related content (e.g. commits.md and commit-conventions.md)
Source vs target collision — a file with the same name already exists at the target scope

Files that appear in only one source and have no target-scope sibling are not promotion candidates — they are correctly scoped already.

3. Evaluate each candidate

For each candidate group, read every file and apply this checklist. Every "yes" makes promotion less appropriate:

Signal	What to look for
Owner-specific identifiers	Org or user names (`OrgA`, `some-user`), GH repo URLs, container registry paths (`ghcr.io/<org>/...`), GitHub App IDs, secret names, named workspaces (Terraform Cloud, Spacelift)
Owner-specific conventions	Label sets (`docs` vs `documentation`), reviewer usernames (`@user` vs bare `user`), project-routing tables, CI tool choices (Renovate vs Dependabot)
Path-scoped frontmatter that differs	A `paths:` glob that genuinely targets a different directory shape per source
Tooling assumptions	Helm chart names, image-updater configurations, deploy-values schemas tied to one stack
Already covered upstream	A user-global rule, a plugin skill, or a friction-findings note already says the same thing — promoting would duplicate, not consolidate

Then ask the inverse: what's generic about this file? Is there a kernel (a self-review guard, a "use conventional commits" preamble, a generic checklist) that applies regardless of owner?

4. Recommend an action per candidate

Pick exactly one of four:

Action	When	What it does
Promote as-is	All sources have effectively identical content; no owner-specific signals; not already upstream	`git mv` one source copy to the target scope; delete siblings
Extract kernel	Sources share a generic core but each carries owner-specific deltas	Write the generic content as a new file at the target scope; trim each source down to only the deltas, with a one-line link back to the target file
Keep scoped	Content genuinely differs per owner; a unified version would force one set of conventions on the others	Leave files where they are; optionally add a one-line frontmatter comment explaining the divergence so future readers don't re-evaluate
No action (already upstream)	The user-global rule or a plugin skill already covers this	Optionally delete the redundant source copies; do not write to the target

5. Confirm before writing

For each candidate group, present:

The grouped files (paths)
The diff between sources (diff <a> <b> for two-source cases; a 3-way summary for more)
The recommended action with a one-sentence justification
The four alternatives via AskUserQuestion

Only proceed on explicit approval. Do not bundle multiple candidate decisions into one prompt — each gets its own approval round-trip so the user can redirect on any single one.

6. Execute the approved action

Action	Mechanics
Promote as-is	`git mv <source-1> <target>` to preserve history, then `rm` the other sources. If the source repos are independent (separate `.git` per scope), use `cp` + `rm` instead of `git mv`.
Extract kernel	Use `Write` to create the target file with the generic content. Use `Edit` on each source to remove the now-shared content, replacing it with one line of the form `> Generic guidance: see [\`<rel-path-to-target>`](<rel-path-to-target>).`
Keep scoped	Optionally `Edit` each source to add an HTML comment `<!-- intentionally scoped: <reason> -->` near the top so the next pass through this skill skips it quickly.
No action	Optionally `rm` the redundant sources; never write to the target.

After every write, run git status against each affected repo so the user sees exactly what changed before any commit happens.

7. Report

Emit a final summary table:

Source files	Action	Target	Notes
`OrgA/.claude/rules/foo.md`, `OrgB/.claude/rules/foo.md`	Keep scoped	—	Org-specific label conventions
`OrgA/.claude/rules/bar.md`, `OrgB/.claude/rules/bar.md`	Promote as-is	`./.claude/rules/bar.md`	Identical content, no owner signals

End with the next step the user should take (typically: review git status in each affected repo, then commit per-repo with conventional-commit messages — meta-promote itself does not commit).

Demotion (inverse direction)

Occasionally a rule lives at user-global scope but is genuinely owner- or project-specific. The same evaluation applies in reverse: if a ~/.claude/rules/<x>.md references one org's tooling and would mislead anyone outside that org, propose moving it down to the appropriate <owner>/.claude/rules/. Use the same four-action menu — "Promote" becomes "Demote", "Extract kernel" stays the same.

Anti-patterns to avoid

Don't	Do
Promote two same-named files just because the names match	Diff their contents and apply the checklist — same name often hides genuinely different rules
Bundle "promote A and B" into one approval prompt	One candidate, one prompt — the user may agree on A and reject B
Use `rm -rf` on a scope's `.claude/` to "clean up" after promotion	Remove only the specific files you're promoting; leave the rest of the scope alone
Commit the promotion as part of the skill	Leave commits to the user — the skill produces a clean working tree the user can review and split into per-repo commits
Promote when an upstream rule already covers it	Recommend "no action" and (with approval) delete the redundant source(s)

Notes

This skill reads broadly and writes narrowly. The discovery phase touches every .claude/ scope under scope-path; the write phase touches only the specific files the user approved.
When source scopes are in separate git repos, the user must commit in each repo independently. Do not attempt cross-repo atomic operations.
Pair with meta-audit for a follow-up sanity check after promotion: meta-audit will catch any frontmatter that broke during the move.