/machinist
Use Machinist to create, assign, and monitor software tasks. Use when a coding agent needs to work with Machinist, its GitHub issue workflow, intake labels, direct runs, or managed queue.
$ npx -y skills add owainlewis/machinist --skill machinist --agent claude-codeHow it fires
How this skill gets triggered: by you, by Claude, or both.
- Fires itselfAuto-invocation. Claude auto-loads it when your prompt matches the work.Auto-invocation is when the right skill fires by itself at the right moment, driven by a FLOW.md router and a hook, instead of you invoking it by name. It is the difference between a skill being installed and a skill actually getting used.Read the full definition →
- You can call itInvoke it directly when you want it.
- Slash command
/machinist
Context preview
The summary Claude sees to decide when to auto-load this skill.
Use Machinist to create, assign, and monitor software tasks. Use when a coding agent needs to work with Machinist, its GitHub issue workflow, intake labels, direct runs, or managed queue.
SKILL.md
machinist.SKILL.mdname: machinist
description: Use Machinist to create, assign, and monitor software tasks. Use when a coding agent needs to work with Machinist, its GitHub issue workflow, intake labels, direct runs, or managed queue.
Machinist
Machinist turns a task or GitHub issue into an implemented, independently reviewed, and checked pull request. It never merges the pull request.
Core model
- A task is one GitHub issue in the target repository, or a plain description.
- Assigning a task means starting `machinist run` or queuing `machinist submit`.
- Assign the same issue again to continue interrupted work. The `task-to-pr` command
reuses an existing branch, worktree, and pull request for the task.
- When `MACHINIST_RUN_ID` is set, the agent is already inside a Machinist run. Follow the
assigned task and do not start or submit another run.
Create a task
Reuse a supplied issue when it is open and belongs to the current repository. Otherwise create one issue with `gh issue create`. Keep it focused on one observable outcome and preserve the user's constraints. Do not invent implementation details that the request does not decide.
gh issue create --title "<short outcome>" --body "<problem, outcome, constraints, and acceptance evidence>"
Use the issue URL returned by GitHub for every later command.
Assign a task
Use direct mode for immediate local work. Pass an absolute Git worktree path:
machinist run \
--command=task-to-pr \
--repo=/absolute/path/to/repository \
--prompt="Complete https://github.com/owner/repository/issues/123"
Use managed mode when the control plane and worker are already running. Pass the logical repository name from `worker.toml`:
machinist submit \
--command=task-to-pr \
--repo=repository-name \
--prompt="Complete https://github.com/owner/repository/issues/123"
`submit` prints a job ID. Follow managed work in the local control-plane UI.
When the shared configuration defines a `[triggers.github.<name>]` trigger, adding its configured input label, normally `machinist:requested`, delegates that issue through the managed queue. Machinist verifies the label event and actor, admits the job durably, then replaces the input label with `machinist:queued`. The label has no effect when that GitHub trigger or its repository is not configured. `machinist:requested` and `machinist:queued` are intake labels; they do not report progress after the job starts.
Report status
Check the run in the control-plane UI or the `machinist run` output, then the linked pull request and its checks. The command finishes as completed, blocked, or failed with a short summary.
- For blocked work, fix the reported cause or answer the question, then assign the same
issue again.
- For completed work, hand the pull request to a person. Never merge unless that person
explicitly decides to do so.
When reporting status, include the issue URL, job ID when managed, pull request URL when created, checks, and blocker or next human action.
Read more
name: machinist description: Use Machinist to create, assign, and monitor software tasks. Use when a coding agent needs to work with Machinist, its GitHub issue workflow, intake labels, direct runs, or managed queue.
Machinist
Machinist turns a task or GitHub issue into an implemented, independently reviewed, and checked pull request. It never merges the pull request.
Core model
- A task is one GitHub issue in the target repository, or a plain description.
- Assigning a task means starting `machinist run` or queuing `machinist submit`.
- Assign the same issue again to continue interrupted work. The `task-to-pr` command
reuses an existing branch, worktree, and pull request for the task.
- When `MACHINIST_RUN_ID` is set, the agent is already inside a Machinist run. Follow the
assigned task and do not start or submit another run.
Create a task
Reuse a supplied issue when it is open and belongs to the current repository. Otherwise create one issue with `gh issue create`. Keep it focused on one observable outcome and preserve the user's constraints. Do not invent implementation details that the request does not decide.
gh issue create --title "<short outcome>" --body "<problem, outcome, constraints, and acceptance evidence>"
Use the issue URL returned by GitHub for every later command.
Assign a task
Use direct mode for immediate local work. Pass an absolute Git worktree path:
machinist run \ --command=task-to-pr \ --repo=/absolute/path/to/repository \ --prompt="Complete https://github.com/owner/repository/issues/123"
Use managed mode when the control plane and worker are already running. Pass the logical repository name from `worker.toml`:
machinist submit \ --command=task-to-pr \ --repo=repository-name \ --prompt="Complete https://github.com/owner/repository/issues/123"
`submit` prints a job ID. Follow managed work in the local control-plane UI.
When the shared configuration defines a `[triggers.github.<name>]` trigger, adding its configured input label, normally `machinist:requested`, delegates that issue through the managed queue. Machinist verifies the label event and actor, admits the job durably, then replaces the input label with `machinist:queued`. The label has no effect when that GitHub trigger or its repository is not configured. `machinist:requested` and `machinist:queued` are intake labels; they do not report progress after the job starts.
Report status
Check the run in the control-plane UI or the `machinist run` output, then the linked pull request and its checks. The command finishes as completed, blocked, or failed with a short summary.
- For blocked work, fix the reported cause or answer the question, then assign the same
issue again.
- For completed work, hand the pull request to a person. Never merge unless that person
explicitly decides to do so.
When reporting status, include the issue URL, job ID when managed, pull request URL when created, checks, and blocker or next human action.
Open source software factory infrastructure for advanced AI coding workflows