Propose automation (skills / agents / hooks) for a repository

Project-agnostic, global skill. It scans the current repo, infers how work actually flows through it, and proposes a SHORT, ranked, high-ROI plan of skills, agents, and hooks tailored to it - then scaffolds only what the user approves. Bias to restraint: a few high-confidence proposals beat a long list.

It pairs with /init: /init documents a repo (CLAUDE.md); this proposes the automation layer on top, and should read CLAUDE.md/README first to ground itself.

Operating principles (the reusable judgment - apply these throughout)

1. Skill vs agent vs hook:

• Skill = a repeatable, context-rich, steerable procedure the user invokes

(/name); runs in the main thread with project knowledge.

• Agent = isolatable / parallel / noisy work (large reads, fan-out, web

search). Usually spawned inside a skill as a step, not as the top-level interface. Only define a custom agent (.claude/agents/) when you need a named, reusable role with a restricted toolset.

• Hook = deterministic automation that should always run (validation,

formatting) via settings.json or a git hook. Prefer a hook over a skill when no judgment is needed and it must not be forgotten.

1. Project vs global placement:

• Project (./.claude/...) when coupled to this repo's conventions/paths;

travels and is versioned with the repo. This is the default.

• Global (~/.claude/...) only when genuinely project-agnostic.

1. Thin orchestrator: a generated skill owns the step sequence and guardrails and

references the repo's single sources of truth (CLAUDE.md, README, config, style guides). It must not duplicate them, or the two copies drift.

1. ROI model: value ~ frequency x time-saved-per-run x error-reduction; cost =

build + ongoing maintenance + cognitive overhead. Propose only when value clearly beats cost. Something run a couple of times is not worth a skill.

1. Restraint: always include a "Deferred / not worth it" section. Resist sprawl;

skills are maintenance.

1. Respect the repo: follow conventions you discover (style, naming, and any

integrity/firewall constraints in CLAUDE.md). Never fabricate repo facts.

Procedure

1. Orient (scan)

• Read CLAUDE.md (root and nested), README*, and any existing .claude/skills

and .claude/agents (so you do not duplicate what exists).

• Read manifests/config to identify the stack and its tasks: package.json,

pyproject.toml, Makefile/justfile, CI workflows, lint/format config, etc.

• Skim the directory tree and recent git log to see what kinds of changes happen

and how often (frequency feeds the ROI model).

• For a large or unfamiliar repo, delegate the sweep to the Explore (or

general-purpose) agent and work from its summary, to keep your context clean.

2. Find the real pain (ask)

Static analysis cannot see habits, and the highest-ROI automation comes from what the user does repeatedly and dislikes. Ask 2-3 targeted questions, e.g.:

• "What do you do in this repo repeatedly that feels tedious or error-prone?"
• "What multi-step task would you most want behind one command?"
• "Anything that must always happen but sometimes gets forgotten?"

Treat your scan-based ideas as hypotheses to confirm, not conclusions.

3. Propose (ranked plan, do NOT build yet)

Present a SHORT ranked list - aim for the 2-4 highest-ROI items. For each:

• name + one-line purpose;
• the workflow loop / pain it addresses;
• type (skill / agent-backed skill / custom agent / hook) with the reason;
• placement (project or global) with the reason;
• ROI rationale (frequency, time saved, error reduction vs build + maintenance);
• guardrails it needs and which SoT docs it would reference.

Then a "Deferred / not worth it (yet)" section naming what you intentionally left out and why. Building nothing in this step is correct.

4. Scaffold (only what the user approves)

For each approved item:

• Create it in the correct place and format: .claude/skills/<name>/SKILL.md,

.claude/agents/<name>.md, or a hook (settings.json entry and/or a git hook plus a small script).

• Write it as a thin orchestrator that references the repo's SoT docs; bake in the

guardrails identified in step 3.

• If it needs validation/help, add a small script and have the skill call it.
• Match repo conventions discovered in step 1 (style, any no-emoji rule, any

report/output firewalls).

• Remind the user that skills/agents are indexed at session start, so a restart is

needed before the new /command autocompletes.

5. Record the plan

Offer to save the full ranked plan (including the deferred items) to a file in the repo (e.g. AUTOMATION-PLAN.md) so the deferred ideas are not lost.

Guardrails

• Propose in step 3; build only after approval in step 4. Never auto-build.
• Never duplicate content that belongs in a SoT doc - reference it.
• Honor any integrity/firewall constraints found in the repo's CLAUDE.md.
• Keep proposals few and honest; flag low-ROI ideas as deferred rather than shipping them.