factory-supervise

Coordinate one or more tickets inside a Herdr-managed Pi sandbox using specialist subagents, isolated worktrees, atomic factory state, usage accounting, and at most three work-review rounds. Use when starting factory orchestration in this session, not for planning, implementation, or review itself. Do not apply when the user is continuing an already-supervised ticket; those prompts resume this session by ticket id.

Quality

92%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Quality

Content

92%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

An expertly structured orchestration skill: fully executable commands, explicit validation gates and feedback loops at every stage boundary, and clean deferral of detail to a single one-level reference and real scripts. The only real cost is token weight — a few duplicated prohibitions and an inline version floor could be consolidated without losing coverage.

Suggestions

Consolidate the repeated no-polling and 'steered prose is not the contract' prohibitions into one statement in the stage-boundary section; the duplication at lines 30/65/71 and 71/88 can be trimmed.

Move the 'Herdr is at least 0.8.2' version floor (and other environment prerequisites) into references/runtime-protocol.md#configuration so version-sensitive detail does not sit in the always-loaded body.

The stage-boundary command list repeats 'node <skill-dir>/scripts/fstate/cli.mjs' verbatim four times; a short prefix variable or a pointer to the runtime-protocol catalog would save tokens without losing executability.

Dimension	Reasoning	Score
Conciseness	The body is telegraphic and assumes Claude's competence throughout, with no concept explanations or tutorial padding. Minor trimmable instances remain: the no-polling prohibition is stated three times (lines 30, 65, 71), 'Do not treat steered prose as the contract' repeats (lines 71, 88), and the version-sensitive floor 'Herdr is at least 0.8.2' sits in the main flow rather than a config/reference section.	4 / 5
Actionability	Every phase is backed by exact, executable commands (git rev-parse --show-toplevel, the four stage-boundary commands, fstate task transition edges, pane-naming formats) plus a copy-paste reviewer spawn prompt. Not 4: coverage of the common cases is complete and copy-paste ready, with no pseudocode gaps.	5 / 5
Workflow Clarity	Stages are explicitly sequenced (plan → work → review → wrapup → done) with a numbered boundary checklist, explicit validation gates ('If the exit code is 3 or 4, call subagent_resume once with the stderr line'), a bounded feedback loop (at most three review rounds, resume-once on contract failure), explicit stop conditions, task state-machine edges, and a crash-recovery pointer. Not 4: checkpoints, error-recovery loops, and limit enforcement are all explicit, matching the top anchor.	5 / 5
Progressive Disclosure	The body is an operational overview that defers the command catalog, config shape, state ownership, display metadata, and recovery details to references/runtime-protocol.md via well-signaled one-level anchor links (all anchors verified to exist) and to real, present scripts (fstate/cli.mjs, pi-session-reader.py, review-packet.py, github-related.mjs). Not 4: the split is clean and navigation is easy, with no bulk reference material inlined.	5 / 5
	Total	19 / 20 Passed

Description

92%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong description: concrete capabilities, an explicit positive trigger, and unusually good negative boundaries that separate it from sibling plan/work/review skills and from resume flows. The only weakness is trigger-term breadth — it relies on environment jargon where a few natural synonyms would help.

Suggestions

Add one or two natural user phrasings as triggers (e.g., 'run the factory' or 'supervise tickets') so the description matches how users are most likely to phrase the request.

Consider spelling out that 'factory orchestration' covers spawning and supervising specialist subagents end to end, so users who only know the words 'supervise' or 'orchestrate tickets' still land here.

Dimension	Reasoning	Score
Specificity	'Coordinate one or more tickets... using specialist subagents, isolated worktrees, atomic factory state, usage accounting, and at most three work-review rounds' names multiple concrete mechanisms with comprehensive coverage. Not 4: the action list has no meaningful coverage gaps.	5 / 5
Completeness	'Use when starting factory orchestration in this session, not for planning, implementation, or review itself. Do not apply when the user is continuing an already-supervised ticket' answers what, when, and when-not explicitly. Not 4: the 'when' clause includes concrete triggers plus negative boundaries, matching the top anchor.	5 / 5
Trigger Term Quality	'Use when starting factory orchestration in this session' and 'continuing an already-supervised ticket' are natural trigger phrases for this domain, but coverage leans on internal jargon ('Herdr-managed Pi sandbox', 'atomic factory state') and omits common variations like 'run the factory' or 'supervise tickets'. Not 3: the terms present are the ones a user of this environment would actually say; not 5: synonyms and phrasings are thin.	4 / 5
Distinctiveness Conflict Risk	The description carves a clear niche (supervision only) and explicitly excludes the sibling specialist skills ('not for planning, implementation, or review itself') and the already-supervised resume case, minimizing wrong-skill triggering. Not 4: conflict risk is addressed directly rather than merely reduced.	5 / 5
	Total	19 / 20 Passed

Validation

87%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 1 missing, 1 deeper-than-1-level, 2 suspicious	Warning
referenced_paths_exist	Referenced path issues: 2 deeper-than-1-level	Warning

	Total	14 / 16 Passed

Repository: geut/factory-skills
Path: skills/factory-supervise/SKILL.md
Commit: 8cd55ad

Reviewed: 3 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.