Propose Automation

---
name: propose-automation
description: Scan the current repository, infer its workflow, and propose a short, ranked, high-ROI plan of Claude Code skills, agents, and hooks tailored to it - then scaffold only the items the user approves. Global and project-agnostic. Trigger when the user says "what skills should this project have", "propose automation", "set up skills for this repo", "scaffold agents/hooks", or "plan automation".
---

# 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.
2. **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.
3. **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.
4. **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.
5. **Restraint:** always include a "Deferred / not worth it" section. Resist sprawl;
   skills are maintenance.
6. **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.