Tool Builder

SKILL.md preview

---
name: Tool Builder
description: Build automation scripts from action-converter suggestions and recurring manual tasks
var: ""
tags: [dev, build]
depends_on: [action-converter]
---
<!-- autoresearch: variation B — sharper output via agent-friendly CLI quality gates and a pre-commit checklist -->

> **${var}** — Specific tool or automation to build. If empty, finds opportunities from recent action-converter outputs and logs.

If `${var}` is set, build that specific tool instead of auto-selecting.

Today is ${today}. Read `memory/MEMORY.md` and the last 7 days of `memory/logs/` for context before starting.

Your job is to ship one small, self-contained CLI tool that future Aeon runs (and the operator) will actually re-use. The bar for "shippable" is the **Quality gates** in step 3 — a tool that doesn't pass them is not done.

## Steps

### 1. Find an opportunity (skip if `${var}` is set)

Score candidates from these sources, then build the highest-scoring one. Each source contributes at least one concrete pattern; do not invent ideas with no grounding.

| Source | What to look for |
|--------|------------------|
| `memory/logs/` (last 14 days) | Action-converter outputs and recurring tasks; the same shell incantation (`gh api …`, `curl … \| jq …`) repeated across days |
| `.outputs/action-converter.md` | Latest action-converter chain output, if present |
| `memory/MEMORY.md` | Stated goals, tracked items, "Next Priorities" |
| `memory/cron-state.json` | Skills with consecutive failures — a retry/diagnose helper may be the right tool |
| `scripts/` directory | Existing TODOs in headers, near-duplicate scripts that could share a helper |

**Score each candidate** as `occurrences × estimated_minutes_saved_per_run × reusability` where:
- `occurrences` = distinct days the pattern shows up (1 if speculative)
- `estimated_minutes_saved_per_run` = realistic, not aspirational
- `reusability` = 1 (one-skill use) to 3 (used by many skills or operator-facing)

Drop candidates that:
- Already exist in `scripts/` (run `ls scripts/` and check). Treat near-name matches as duplicates unless clearly different.
- Are better solved by a new skill than a script (multi-step reasoning, LLM-driven output → skill, not script).
- Have score < 4. If nothing scores ≥ 4, abort with `./notify "tool-builder: no opportunity scored ≥ 4 today — skipping"` and log the top 3 candidates to `memory/logs/${today}.md` for next time. Do not build a low-value tool just to ship something.

Write the chosen candidate's name, source, score, and one-sentence purpose into a working note before building.

### 2. Design the tool

State explicitly, in 5 lines max:
- **Name**: kebab-case, ≤24 chars, no extension (e.g. `cron-doctor`, not `cron_doctor.sh`)
- **Purpose**: one sentence, present tense
- **Inputs**: positional args, flags, env vars, stdin
- **Outputs**: stdout shape (text or JSON), stderr usage, file writes (if any), exit codes
- **Dependencies**: prefer `bash + jq + gh + curl + date` (already available). Node.js or Python only when bash gets ugly. **No `npm install`, no `pip install`.**

### 3. Build it — Quality gates (all must pass)

Write to `scripts/{tool-name}` (no extension). Match the conventions of `scripts/eval-audit` and `scripts/skill-runs`. Every shipped tool must satisfy **all** gates below; if a gate doesn't apply, say why in the header comment.

**Header (mandatory):**
```bash
#!/usr/bin/env bash
# {tool-name} — {one-sentence purpose}
#
# Usage:
#   ./scripts/{tool-name}                  # default
#   ./scripts/{tool-name} --json           # machine-readable
#   ./scripts/{tool-name} --dry-run        # show what would happen
#   ./scripts/{tool-name} --help           # this message
#
# Exit codes:
#   0  success
#   1  generic failure
#   64 usage error           (EX_USAGE)
#   75 transient failure     (EX_TEMPFAIL — retry-able, e.g. network)
#   78 missing configuration (EX_CONFIG — e.g. required env var unset)
#
# Used by: {skills or "operator-onl

…