Index of every page on this site: llms.txt
All skills
Run it yourself

Orchestrate several coding tasks or PR reviews in parallel from one Herdr pane or the Herdr app, with any coding agent (Claude Code, Codex, OpenCode, Pi, Cursor or any other CLI agent Herdr supports). Each issue gets its own git worktree, a background Herdr tab and a worker agent; each open PR gets a review worker in a tab of its own. Workers can be different kinds in one run. They stop at gates (spec, implemented, pr), show their gate in the Herdr sidebar and report back to this orchestrator session, which relays the user's decisions. A run is saved to disk, so workers can be resumed with their full conversation later. Use when the user wants to work on multiple issues or tasks at once, e.g. "work on 101 and 102 in parallel", "spin up workers for these issues", "smith 101 102 103", "/smith", "smith 5737 5760" with PR numbers to review them, "use codex workers", "pick N issues and run them in parallel", or "resume yesterday's smith run". Requires Herdr (HERDR_ENV=1) or the Herdr app (hc).

Use this Skill: https://skilld.dev/gh/aslamdoctor/skills/smith

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈253 tokens for metadata: the name and description. ≈2.8k when used: this file. ≈9.1k more on demand in 5 files.

Description uses 12.6% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈1011 characters, or 12.6%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Smith

This session is the orchestrator. It never writes task code itself. It creates workers, sends them prompts, watches them, and brings their questions to the user. Workers do the work in their own worktree and tab.

Workers are Smith's copies, named after their task type and task: code-<id> for an issue or slug (code-101) and review-<id> for a PR (review-5737). The same name is the address and what the sidebar, toasts and reports show. This orchestrator's own tab is SMITH-ORC<n>, where <n> is its terminal address from the first digit on, uppercased (t7 gives SMITH-ORC7). Older runs keep the names recorded in run.json (smith-<id>, i<id>).

Prompt templates are in references/prompts.md. Backend-specific steps are in references/<backend>.md; this file points at their sections as "references/<backend>.md § <name>".

0. Pick the backend

Condition Backend
HERDR_ENV=1 herdr
HC_TERMINAL_ID set and hc server status succeeds herdr-app
Both Ask the user once which one to use
Neither Say "smith needs a Herdr TUI pane or the Herdr app", and stop

Read references/<backend>.md now and use its sections wherever this file says § <name>. Read references/gotchas.md (the Common section plus your backend's section) before the first run in a session. Read each reference file with your file-read tool, or one cat per file, never several joined by echo separators: zsh expands a word that starts with = (echo ======), fails, and the rest of the command never runs.

Agent support

See references/<backend>.md § Agent support. Worker kinds come from Herdr, and tasks in one run can use different kinds.

1. Preflight

  1. Run references/<backend>.md § Preflight. It checks the environment, finds your own kind, settles worker kinds and creates or reuses the run directory ~/.smith/runs/<repo>-<YYYY-MM-DD> (-app is added on herdr-app).
  2. If a project or global rule forbids worktrees, tell the user this skill needs them and ask once. Record a scoped exception in your memory or notes if they agree.

2. Pick the tasks and the setup

Tasks. Use the IDs the user gave. Classify each ID before anything else, since a PR number and an issue number look the same:

Check Task type Gates Spawn
gh pr view <id> --json state,author,url succeeds and state is OPEN review findings / posted spawn.sh <id> - - (no worktree, runs in the repo root), Review kickoff
Anything else (an issue, a slug, a merged or closed PR) code spec / implemented / pr as below, Kickoff

A full PR URL is a review task for that PR, even in another repo. Keep the URL as the task ID everywhere (gh pr view <url>, spawn.sh <url> - -, the kickoff, send.sh, close.sh): a bare number would point at this repo. Worker names shorten it to review-<repo>-<number>.

Show the type per ID in the setup table. A run can mix both types. If a code-task issue already has an open PR (gh pr list --search "<id> in:title,body" --state open), ask whether to review that PR, resume its worker for review fixes (§ 8), or start a fresh code task. If they asked you to choose ("pick 3"), list open candidates (e.g. with gh issue list), read each one's blockers and dependencies, and choose tasks that can run in parallel without depending on each other's unmerged code. Show a table of the choices and why.

Setup. Detect each value from the repo's instruction files (AGENTS.md, CLAUDE.md, GEMINI.md, .cursor/rules and similar), your memory or notes, and recent branches and PRs (gh pr list --state all --limit 10 --json headRefName,baseRefName). Ask only for what you can't find:

Setting Where to look
Base ref for new branches (code tasks) Project rules, epic or feature-branch notes, recent PR bases
PR base Same as above (often the base ref's branch)
Branch name format Branch-creation rules, recent branch names
Commit format Commit workflow rules
Ship flow A ship skill, or the project's PR rules
Pre-ship review A self-review or preflight skill, if the project has one (else none)
Review skill (review tasks) A PR review skill for the project (e.g. thrive-review-pr), else a plain gh pr diff review with findings only
Test and lint commands Instruction files, package.json / composer.json / Makefile
Worker kind per task Your own kind
Worktree root ~/<repo>-wt/<branch> (override with WT_ROOT)
Gates Default spec / implemented / pr

Show the detected setup as one table and confirm it with the user before spawning anything. Use your structured question tool if you have one, otherwise ask in plain text.

Skills and slash commands differ between agents. When a step uses a skill (a ship or fix-PR flow), give workers the skill's file path ("follow <path>/SKILL.md") rather than a slash command, unless the worker kind is known to load that skill itself.

Dependencies within the run. If task B needs task A's unmerged code, cut B from A's branch (a stacked branch). Otherwise cut every task from the base ref. When two tasks will touch the same shared entry (a docs section, error-code list or registry), decide now which one owns it.

3. Spawn workers

Spawn each worker and deliver the Kickoff prompt (code tasks) or the Review kickoff (review tasks) from references/prompts.md, with your backend's gate instruction: references/<backend>.md § Spawn.

4. Watch

After every prompt that starts work, arm the watcher: references/<backend>.md § Watch. It reports one of:

  • GATE: the worker reached a gate (spec, implemented, pr, or a question).
  • BLOCKED: a dialog or escalation is waiting.
  • STOPPED: no gate, and the worker has gone quiet.
  • GONE: the agent exited.

5. When a watcher reports

  1. Read the worker: references/<backend>.md § Read a worker.
  2. Report to the user based on what fired:
    • GATE spec: the approach in a few lines, deviations from the task, and the worker's open questions as a table with your recommendation for each. Point out conflicts with sibling workers (same method, same docs section).
    • GATE implemented: the commit hash, message and changed files (in the user's commit-report format if they have one), test and lint results, anything the worker changed from the approved spec, and new shared-environment problems.
    • GATE findings: the worker's picker output verbatim (findings table with default picks, questions, coverage gaps), then ask for the picks and the post decision with the same options the review skill gives. Relay them with the Review picks template.
    • GATE posted: the review URL, or that it wasn't posted.
    • GATE question / pr: the exact question or draft text (thread replies, issue comments), verbatim.
    • BLOCKED: what the dialog asks.
    • STOPPED / GONE: what the screen shows, and whether to nudge, resume or drop the task.
  3. Ask for decisions, batching pending decisions across workers. Then relay them: references/<backend>.md § Relay answers.
  4. Before you say "shipped", check the PR yourself: base, reviewers, labels, resolved threads and file list.
  5. After handling each report, run RUN=<run> S/done.sh --ask. When it exits 0, every open worker has reached its last gate (pr for code tasks, posted for review tasks) or is gone. End your report with one question: "All N workers are done. Close their tabs, their watchers and this orchestrator tab?" A yes runs § 7. A no closes nothing, and you don't ask again: done.sh --ask exits 3 until new work starts (a spawn or a send). Exit 1 means some workers are still busy; say nothing about cleanup.

Keep a status table in every report: references/<backend>.md § Board.

6. Ship

Code tasks only. Only on the user's go-ahead per task, using the Ship template. Pre-answer the ship flow's routine questions with the user's standing answers (for example: local automated QA No because the dev site points at the main checkout, staging skipped from a worktree, default reviewer). Ask once whether those answers apply to all workers in the run.

Ship stacked tasks as stacked PRs (see Stacked ship in the templates). After a parent PR merges, the child needs a rebase and its PR switched to the real base.

7. Wrap up

On a yes to the § 5 question, or whenever the user says "close everything", run one command: RUN=<run> S/close.sh --all --self on herdr, RUN=<run> S/app/close.sh --all --self on herdr-app (details in references/<backend>.md § Wrap up). It closes the worker tabs and stops their watchers. Then, once your current turn ends, it closes your own orchestrator tab too. Report what it closed and any warnings in that same turn, and make it your last message: the tab goes right after. If a worker didn't close cleanly, the orchestrator tab stays open so you can sort it out.

Leave out --self when the user wants only the workers closed ("close the workers but keep this tab"), or when closing some tasks by id.

It keeps the worktrees, branches and run.json, since review fixes resume from them. The orchestrator's conversation can be picked up again with the agent's own resume (claude --resume). Clean up only what this run created, and only when the user agrees. When everything has merged, offer separately to remove the worktrees, delete the local branches and archive the run directory.

8. Resume a run

For review feedback, a follow-up or a session that lost track of a run ("resume yesterday's smith run"). A resume skips § 1 to 3: no new run directory.

  1. Find the run with ls -t ~/.smith/runs/ and read its run.json. Resume a run only with its own backend (run.json backend, none = herdr). If it differs from the current one, say so and stop.
  2. Restart or reuse each worker in its old conversation: references/<backend>.md § Resume. If that isn't possible, start a fresh worker and send a short catch-up prompt (issue, PR, current gate, decisions so far).
  3. Send the follow-up prompt, e.g. "<reviewer> reviewed PR <n>. Follow <fix-PR skill path>, stop with the fixes and draft replies for approval." Then watch as usual.
  4. Stacked children: once the parent's fixes are pushed, tell the child to rebase onto the parent branch. After the parent merges, rebase it onto the real base and switch the PR's base.

Rules

  • The user approves every spec, every ship and every text posted to GitHub or anywhere else. Workers never decide for the user, and neither do you. Relay, recommend, wait.
  • Workers stop at each gate and ask in plain text, never through an interactive dialog. The kickoff tells them this.
  • Never focus or close tabs, terminals or worktrees you didn't create. Never stop the Herdr server.
  • Your own replies to the user follow the user's normal reporting rules.

Install for other agents

The skill is a plain folder in the Agent Skills format. Symlink it into each agent's skills directory so it updates in one place:

ln -s ~/.claude/skills/smith ~/.agents/skills/smith   # shared dir (Codex, OpenCode, Pi and others read it)
ln -s ~/.claude/skills/smith ~/.codex/skills/smith    # Codex

For an agent without skill support, point it at this file: "Read ~/.claude/skills/smith/SKILL.md and follow it."

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning1mo3 checks · Risk SAFE
  • Gen Agent Trust Hub1mo

    This skill acts as an orchestrator for parallel coding tasks by managing multiple worker agents. It presents an indirect prompt injection surface as it reads external data from GitHub and worker outputs, but it implements mandatory user approval gates for all code-writing and shipping actions.

  • Socket1mo

    No alerts

  • Snyk1mo

    Risk: MEDIUM · 1 issue

Signed by skilld at c123387. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 2 days ago.

Activeupdated 4 days ago

README badge

README badge for aslamdoctor/skills/smith