Index of every page on this site: llms.txt
All skills
jetbrains avatar

/writing-workflow-skills

@e85862d
by jetbrainsjetbrains/thinkrail8.4k stars
532
Run it yourself

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.

Use this Skill: https://skilld.dev/gh/jetbrains/thinkrail/writing-workflow-skills

Nothing lands on disk. Nothing to clean up.

Fork this Skill

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

SKILL.md

≈73 tokens for metadata: the name and description. ≈1.8k when used: this file.

Description uses 3.7% 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 ≈293 characters, or 3.7%.

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.

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), retire rather than delete them when the work lands (a task-spec gets status: done; only the user removes artifacts), and promote anything durable to specs before retiring them.
  • 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).

Source: SKILL.md on GitHub

No rule matched.

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.

No alerts22d3 checks · Risk SAFE
  • Gen Agent Trust Hub22d

    This skill is a standard procedural checklist for developers to follow when creating or modifying workflow-related skills within the project. It contains no executable code, network calls, or dangerous commands.

  • Socket26d

    No alerts

  • Snyk26d

    Risk: LOW · No issues

Signed by skilld at e85862d. 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 last week

README badge

README badge for jetbrains/thinkrail/writing-workflow-skills