Writing Workflow Skills

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 concept (one topic's reusable rules/mental model — no steps, no handoffs).
• 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.