Use when adding a new workflow skill to pi-thinkrail-workflow, changing an existing workflow skill's role, trigger, handoff, or structure, or checking a workflow skill against the workflow system's rules. Not for authoring general-purpose skills outside this package.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Use when adding a new workflow skill to pi-thinkrail-workflow, changing an existing workflow skill's role, trigger, handoff, or structure, or checking a workflow skill against the workflow system's rules. Not for authoring general-purpose skills outside this package.
Writing Workflow Skills
The authoring checklist for workflow skills in packages/pi-thinkrail-workflow. It carries the what
to do; every why — the concept model, the three roles, the meta-rules cited as "(rule N)" below —
lives once in the workflow-system spec beside this directory, skills/SPEC.md. Read that spec
first; where this checklist and that spec disagree, the spec wins.
Workspace guard. This checklist edits packages/pi-thinkrail-workflow in the thinkrail repo. If
that package is not in the current workspace (a ThinkRail-managed project, where these skills are a
read-only staged cache), the family cannot be extended from here: say so in one line and stop — the
terminal state for foreign workspaces.
Design (before writing)
Read skills/SPEC.md: concept model, the three roles, meta-rules 1–15.
Scope the skill to one externally reachable workflow — or, for a concept, one topic (rule 1).
Internal forks, branches, stages, and shared tails are sibling docs, planned with the choice
rules in the doc (or spine) before the fork; a doc is promoted to its own skill when it needs
independent addressability (an external caller, a genuine self-trigger, or a direct entry point
such as a /skill: command seed) — never for shape or size alone.
Pick the role (rule 2): router (classification rules + handoffs, nothing else), worker
(one phase's steps), or (one topic's reusable rules/mental model — no steps, no
handoffs).
concept
For a concept: confirm a second skill needs it (rule 3) — reference detail with a single
consumer stays a sibling file, not a concept skill.
Pick the ending (rule 6): a router ends by naming what runs next; a worker ends with a fixed
successor, back to its caller, or a declared terminal state — an internally forking worker ends
by naming the sibling doc that continues the flow, with the terminal state declared in the doc
where the flow ends; a concept has no ending at all — it writes no ending section, control
simply returns to its reader. Know the exact wording before writing the body.
If the change reshapes the system itself — a new role, a new meta-rule, a changed entry model or
topology — stop: update skills/SPEC.md first, then come back here (rule 13).
Write
Name the skill verb-first, active voice, kebab-case (rule 15): a gerund for process skills, the
topic for a concept — name the work or the insight, never the artifact or a role. Directory
name = frontmatter name.
Create skills/<name>/SKILL.md with frontmatter name + description. Nothing else changes —
package.json's pi.skills already points at ./skills.
description = triggering conditions only, "Use when …" (plus a "Not for …" negative trigger if
the boundary is confusable) — never a summary of the steps (rule 5). Skills are reached by
routing; a self-trigger description is for unmistakable triggers only (rule 4).
Keep every file under ~150 lines (rule 3) — the SKILL.md spine and each sibling doc. Internal
workflow nodes (branches, stages, shared tails) and heavy reference material live in sibling
docs inside skills/<name>/, named in the exact step that hands to them; the spine carries the
doc map, and each internal-node doc opens with a one-line contract (entry state, what it saves,
where control goes next).
Say each thing once (rule 7): cross-reference other skills by name; never inline another skill's
steps, never force-load its files.
Put gates where discipline matters, matching the form to the failure (rule 11): prohibitions +
red flags for discipline violations, positive recipes for output shape.
Durable output goes to the spec graph (rule 8). If the workflow needs ephemeral working files —
resume state, scratch plans — declare them (rule 9): name their shape in the skill and put them
in the workspace's gitignored .thinkrail/context/ (the home for every temp doc), consume/delete
them when the work lands, and promote anything durable to specs before cleanup.
End the body by naming the ending chosen in Design (rule 6) — a concept skips this: no ending
section.
Register (rule 12)
Add one routing line in the router that owns the new skill: the root router
(skills/choosing-a-workflow/SKILL.md) by default, or the nearest sub-router when the skill is
a branch under an already-routed workflow (fractal routing). Exception (rule 4): a skill outside
any router's work classification — self-trigger-only skills and concept skills — skips the
router line; that's a designed property of the skill, never a size call, and it is instead named
in skills/SPEC.md's family table as outside the routing table.
Add or update the skill's row in skills/SPEC.md's Workflow family table, including its
Routed from entry (which router routes to it — or that it sits outside the routing table).
Nothing else should have changed shape — if it did, revisit rule 13 in Design.
Verify by use (rule 14 — currently suspended)
Rule 14 is a known limitation today, not a done-gate (see skills/SPEC.md). When practical,
still run a real request through the new or changed skill and watch it flow: the router (or
the description) triggers it, the body is followed, the ending fires as designed. For a
concept: a referencing skill (or its self-trigger) loads it and its rules are applied.
Either way, keep the family-table row honest: unverified by use until a run has been
observed; update the row when one has.
Red flags — stop and fix
The description mentions any step of the workflow.
The name is noun-first or names an artifact/role instead of the work (rule 15).
The body of a router or worker ends without naming a successor or terminal state.
A concept skill contains steps, routing, a handoff, or an ending section.
The same rules are copied into two skills instead of extracted into a concept (rule 7).
A step restates another skill's (or skills/SPEC.md's) content instead of pointing at it.
An internal node that nothing outside the skill reaches was made its own skill (or given
frontmatter) — internal nodes are sibling docs, not skills (rule 1).
"Too small to need a router line / family-table row." Every skill registers (rule 12); skipping the
router line is only for self-trigger-only skills and concept skills per rule 4 — size is never the
reason.
Calling a skill verified without a real request observed flowing through it — rule 14 is
suspended as a done-gate, but an unobserved skill is still unverified by use, never "verified".
Done (terminal state)
This checklist ends here — no successor skill. Done means: skills/<name>/SKILL.md exists and passes
the checks above, and the router line and family-table row are in place — the row honestly marked
unverified by use until a real request has been observed flowing through the skill (rule 14,
currently suspended as a done-gate).
