Guide · Agent skill
How to use the Writing Workflow Skills agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
Writing Workflow Skills is an agent skill, a folder with a SKILL.md instruction file that an AI agent loads when a request matches its description. This one is a checklist for building workflow skills inside the pi-thinkrail-workflow package of the JetBrains ThinkRail repo. After reading this guide you will know how to install it, how to phrase a request so the agent picks it up, and what it will and will not do on your machine.
Writing Workflow SkillsJetBrains/thinkrail · Apache-2.0 Download the skill Quick start
- 1Get a checkout of the repo. Make sure you have a checkout of the JetBrains thinkrail repository that contains packages/pi-thinkrail-workflow, with skills/SPEC.md beside the skills directory.
- 2Download the ZIP. Download the writing-workflow-skills ZIP from this skill's page on the directory.
- 3Install it. Unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder, or upload the ZIP under Settings → Capabilities → Skills in the Claude apps.
- 4Make a request. Ask the agent in plain language to add, change or check a workflow skill in pi-thinkrail-workflow.
- 5Review the changes. Read the new SKILL.md, the routing line and the family-table row before committing.
What the skill makes the agent do
When you ask an agent to add or restructure a workflow skill in pi-thinkrail-workflow, this skill tells it to follow a fixed sequence: design first, then write, then register the skill, then verify by use. The checklist covers scoping the skill to one workflow, picking its role (router, worker, or concept), choosing how it ends, naming it, and writing a description that only states triggering conditions.
The agent is also directed to read skills/SPEC.md first and to treat that spec as the authority wherever the checklist and the spec disagree. The skill does not run code or use the network. It only shapes how the agent writes skill files.
Install the skill in Claude
Option one is a personal install. Download the ZIP from the skill's page on this directory and unzip it into ~/.claude/skills/. Option two is a project install: unzip it into the .claude/skills/ folder of the project you are working in.
Option three is to upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
- Personal: ~/.claude/skills/
- Project: .claude/skills/ inside your project
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Check the requirements before you use it
The skill only makes sense inside a checkout of the JetBrains thinkrail repository that contains the pi-thinkrail-workflow package. The checklist also depends on the file skills/SPEC.md sitting beside the skills directory. Without that spec file, the checklist's rules cannot be checked against their source.
If you are working in a project managed by ThinkRail where the skills are a read-only cache, the skill tells the agent to stop and say so in one line. It will not help you extend the family from there.
- A checkout of the JetBrains thinkrail repository with pi-thinkrail-workflow present
- skills/SPEC.md beside the skills directory
- Not usable in ThinkRail-managed read-only skill caches
Trigger the skill with natural requests
Agent skills are loaded when a request matches their description, so ask in plain terms that name the workflow package and the action. The description covers adding a new workflow skill, changing an existing skill's role, trigger, handoff or structure, and checking a workflow skill against the workflow system's rules.
Requests that fit well include adding a new skill to pi-thinkrail-workflow, splitting a worker skill into a router and sub-skills, or reviewing an existing workflow skill for naming and routing problems. Requests for general-purpose skills outside this package fall outside its scope.
- "Add a new workflow skill to pi-thinkrail-workflow for handling release notes."
- "Change the handoff in the bug-fix workflow skill so it ends at the review step."
- "Check this workflow skill against the workflow system's rules."
- Not a fit: "Write a general skill that formats my CSV files."
Follow the design, write and register steps
The checklist asks the agent to pick one role for each skill. A router holds classification rules and handoffs only. A worker carries one phase's steps. A concept holds one topic's reusable rules and has no steps, handoffs or ending section.
Each skill must end in a stated way: a router names what runs next, a worker names a fixed successor, a return to its caller, or a declared terminal state. The agent then adds a routing line in the owning router and a row in the Workflow family table in skills/SPEC.md. Skills are expected to be named verb-first and in kebab-case, with the directory name matching the frontmatter name.
- Role: router, worker or concept
- Ending: named successor, return to caller, or terminal state
- Register: routing line plus family-table row in skills/SPEC.md
- Verification: rows stay marked unverified by use until a real run is observed
Safety notes: scripts and network
The skill declares that it runs no scripts and uses no network. Its only effect is on the text of skill files the agent writes. It does, however, direct the agent to edit files in your repo, including adding a routing line and updating skills/SPEC.md, so review those diffs before you commit.
Check the spec and the file list for yourself before installing. The package contains a single file, SKILL.md.
- Runs scripts: no
- Uses network: no
- Files: SKILL.md only
- Expect edits to skills/SPEC.md and the router file during registration
What people use it for
- Adding a new worker skill to pi-thinkrail-workflow with a correct name and frontmatter.
- Splitting an oversized workflow skill into a router spine and sibling docs.
- Changing the handoff or ending of an existing workflow skill and updating its family-table row.
- Reviewing a workflow skill for red flags such as a description that summarises steps.
Frequently asked questions
Is the writing-workflow-skills skill free to use?
The source page lists the licence as Apache-2.0, which governs use of the code. It does not state any price, and the skill itself is a text checklist with no paid component mentioned.
What do I need before I can install writing-workflow-skills?
You need a checkout of the JetBrains thinkrail repository containing the pi-thinkrail-workflow package, and the skills/SPEC.md file beside the skills directory. The skill itself is installed by unzipping it or uploading the ZIP in Claude.
Where do I install an agent skill in Claude?
For a personal install, unzip the skill into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
Why won't the skill work in my ThinkRail project?
In ThinkRail-managed projects the skills are a read-only staged cache, so the skill tells the agent to state that in one line and stop. You need to work in a checkout of the thinkrail repository that includes pi-thinkrail-workflow.
Can I use this skill to write skills for other projects?
No. The skill says it is not for authoring general-purpose skills outside the pi-thinkrail-workflow package. It only teaches how to build workflow skills for that package.
Does the skill run code or access the internet?
No. The skill declares that it runs no scripts and uses no network. It only guides how the agent writes skill files, so you should still review the file changes it makes.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you contribute to or maintain workflow skills in the JetBrains thinkrail repo's pi-thinkrail-workflow package and want consistent naming, routing and registration. Pick something else if you need a skill that does work in your own domain or a general guide for writing skills outside that package.
Download the skill