| name | promote-to-tooling |
| description | Review a tooling change made in a working repo (new skill, script, rule, hook, template, or workflow fix) and promote the universal parts into the clybor-claude-tooling master template. Use when the user says "promote to tooling", "add this to the master tooling", "update clybor-claude-tooling", "parlay this into the template", "should this go in the template repo", or right after building or adapting tooling in any project repo. Runs a universality test, diffs against the master counterpart, generalizes project-specific bits, applies the edit, wires references, and flags downstream repos that need a re-sync. |
Promote to Tooling
clybor-claude-tooling (~/gits/clybor-claude-tooling/) is the master template new repos
initialize from (scripts/init.sh). Tooling improvements born in working repos
(life-crm, client repos) die there unless promoted. This skill is the promotion path.
When to run
- Right after building or meaningfully adapting a skill, script, rule, hook, command,
agent, or template in a working repo
- When the user asks whether a change belongs in the master
- Periodically: "review recent tooling changes for promotion candidates"
The universality test (gate)
From the master rules README: would this apply equally to a Python backend, a
TypeScript frontend, a research repo, a documentation site?
| Verdict | Action |
|---|
| Universal as-is | Port verbatim |
| Universal mechanism, project-specific surface (paths, names, IDs) | Generalize, then port |
| Project-specific (registry formats, client branding, Notion IDs, MCP tool IDs) | Stays in the working repo — record a pointer only |
Where things live in the master
| Working-repo artifact | Master destination |
|---|
| Skill | .claude/skills/<name>/SKILL.md |
| Slash command | .claude/commands/<name>.md |
| Agent definition | .claude/agents/<lane>/<name>.md |
| Hook script | .claude/hooks/ + wire in .claude/settings.json.template |
| Always-on rule | .claude/rules/ (only if universal — see rules README) |
| Gate/utility script | scripts/ |
| Document/folder template | templates/ |
| Router or Hard-Rule text | templates/CLAUDE.md.template |
Workflow
- Name the candidate — file path(s) in the working repo + one line on what it does.
- Universality test — verdict from the table above. Stop here if project-specific.
- Diff against the master counterpart — search the master for an existing equivalent
(skills list,
scripts/, templates/, commands). If one exists, diff and merge into
it — don't create a parallel duplicate.
- Generalize — strip project paths, person names, repo-specific IDs. Pick the right
default over adding a config (KISS).
- Apply — in Cowork,
.claude/ paths need Desktop Commander on the host path
(~/gits/clybor-claude-tooling/...); scripts/, templates/,
docs/ take native writes. In Claude Code, edit directly.
- Wire the references — router row and Key Paths in
templates/CLAUDE.md.template,
skills-list row, settings.json.template hook if applicable. Undiscoverable tooling
is dead tooling.
- Validate — run a changed script once; run
bash scripts/check-context-budget.sh
if always-on files grew; confirm new skill frontmatter parses (name + description,
description under 1024 chars).
- Report downstream impact — repos already initialized do NOT auto-update. List
which active repos should re-sync the changed file (manual copy, or re-run the
relevant
init.sh step). The working repo that originated the change usually keeps
its own specialized version — say so explicitly.
Anti-patterns
- Porting registry- or client-coupled scripts wholesale (life-crm's
new-project.sh is
registry-specific; the master's analog is init.sh)
- Creating a parallel skill when the master already covers the concept under another
name (e.g.,
prd-writer/task-plan vs a working repo's build-prd/build-plan —
diff and merge, don't fork)
- Promoting a non-universal rule into
.claude/rules/ — rules are paid for in always-on
context in every downstream repo
- Promoting without updating
templates/CLAUDE.md.template — the next repo won't know
the tooling exists
- Skipping the downstream-impact report — a master-only fix silently diverges from every
live repo
