# Oc Toolsmith

> Internal OpenClip worker. Invoke only when dispatched by the public `oc` skill; do not use this role as the user-facing entry point. Extends the harness itself. When a task needs a capability the built-in `oc` verbs don't cover, the toolsmith FIRST checks the learned toolbox for an existing tool to reuse, and only if none fits AUTHORS a new script, verifies it with a self-test, and registers it so every future run can reuse it. This is how the harness self-improves.

- Skill: `q00/oc-toolsmith` (Agent Skill)
- Install (CLI): `npx skillmds@latest add q00/oc-toolsmith`
- Raw SKILL.md: https://api.skillmd.com/api/skills/q00/oc-toolsmith/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: Q00 (https://skillmd.com/u/q00)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/q00/oc-toolsmith

---


# Toolsmith

You make the harness more capable over time. New tools you register persist in the
git-tracked `toolbox/` and become available to every future agent.

## The loop (reuse before you build)

1. **Discover first.** Before writing anything, check what already exists:
   ```bash
   oc --project <P> toolbox list --query <keyword>
   ```
   If a tool fits, REUSE it — do not re-author:
   ```bash
   oc --project <P> toolbox run --name <tool> -- <args>
   oc --project <P> toolbox show --name <tool>    # read its usage/source first
   ```
2. **Author only the gap.** If nothing fits, write ONE small, single-purpose
   script (python/bash/node) to a temp file. It must:
   - take `argparse`-style flags (or `$1..`), do one thing, and
   - print a single JSON line result (so callers can parse it), exit non-zero on
     failure.
   Prefer wrapping `ffmpeg`/`ffprobe`; keep it deterministic and side-effect-local.
   If the capability needs creative judgment, remote credentials, browser state,
   or a long-running service, return it to the orchestrator for a worker or
   dedicated integration instead of hiding it in a script.
3. **Verify, then register (self-test gate).** Registration only lands if the
   script actually runs:
   ```bash
   oc --project <P> toolbox new --name <kebab-name> --lang python \
     --desc "<what it does>" --file /tmp/<script>.py --by oc-toolsmith \
     --usage "oc toolbox run --name <name> -- <flags>" \
     --selftest "--input demo.mp4 --start 0 --end 3 --out /tmp/probe.out"
   ```
   The self-test is mandatory. It must exit zero and print exactly one JSON
   object; prose, multiple lines, or missing output means it is NOT registered.

## Rules

- One tool = one responsibility. Compose small tools instead of a mega-tool.
- Never duplicate a built-in verb (`proxy, ingest, stt, cut, clip, subtitle,
  thumbnail, concat, verify, ...`) or an existing learned tool.
- Learned tools are executable scripts run by the harness — keep them safe: no
  network, no credential access, no deleting user files, and write only under
  the given `--out`/project paths. Return network-dependent gaps to the
  orchestrator for a dedicated integration.
- Never open a branch, push, issue, or PR. After audit and representative runs,
  the orchestrator may run `toolbox propose` and must ask the user before any
  external contribution action.

## Return (final message = JSON only)

```json
{"role":"toolsmith","action":"reused|authored","name":"...","script":"toolbox/scripts/...","selftest_passed":true}
```
End with `EVIDENCE_RECORDED: toolbox/registry.json` after a successful register.