engine9-aiengine9-ai/skills/e9-dev-tasks/SKILL.md

e9-dev-tasks

Skill1 starsChanged 48 days agoApache-2.0View on GitHub

Design, author, and debug engine9 JSON5 flow definitions, TaskWorker lifecycle methods, and SQLTaskManager execution. Use only in engine9 development contexts that build multi-step workflows or extend the task execution pipeline; API integrators and operators should use the Task API documentation instead.

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Start from a sample in engine9/server/test/task/*.json5.
line 45
Distinctive:
Use the Task API or MCP documentation only when testing an external scheduling boundary.
line 52
Distinctive:
Rule: Use this skill only for engine9 development: flow authoring, TaskWorker or SQLTaskManager debugging, and task-pipeline extension.
line 56
Very specific:
Rule: Every step must have a unique task_key and a unique name.
line 58
Very specific:
Rule: Do not reuse a worker method such as echo or query as the name of multiple tasks.
line 60

≈ “Common” is an estimate: at least 1 in 5 of the 308,232 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

Develop engine9 tasks and flows

This developer-only skill covers JSON5 flow authoring, TaskWorker lifecycle behavior, and SQLTaskManager execution. Use it while developing in engine9/server, adding SQL, worker, or ETL steps, or debugging the task pipeline. Do not use it merely to schedule existing work through REST or MCP.

Quick reference

Goal	Use
Author or edit a flow	A `.json5` flow definition
Debug flow creation or execution	`TaskWorker.createFlowRun`, `runFlow`, or `executeTaskRun`
Schedule tasks internally	`TaskWorker.scheduleTasks`
Debug polling and task claims	`SQLTaskManager`
Study working definitions	`engine9/server/test/task/*.json5`
Schedule through REST	e9-tasks-api
Schedule through MCP	e9-mcp or e9-cli

Concepts

A flow is a predefined, multi-step workflow represented as JSON5. TaskWorker creates flow runs, schedules and executes task runs, and merges remote execution state. SQLTaskManager polls SQL-backed task state and coordinates execution.

REST integrators schedule a predefined flow by sending flow_id to POST /flow_runs/, or an on-demand worker method by sending path and method to POST /tasks/schedule. They do not author flow definitions through the API.

File format

Flow definitions are .json5 files. Every task requires identifiers that remain unique within the flow and labels that remain unambiguous during remote-state merging.

Field	Requirement
`task_key`	Unique for every task in the flow
`name`	Unique for every task in the flow
Worker method	May repeat only when `task_key` and `name` remain distinct

Workflow

Start from a sample in engine9/server/test/task/*.json5.
Define each SQL, worker, or ETL step.
Assign a unique task_key and unique name to every step.
For a flow bound to one account, load that account's installed plugins and put each step's plugin_id and remote_plugin_id (assignee.bot_id) on the task. If the plugins cannot be loaded, stop and do not write the flow.
Exercise flow creation through TaskWorker.createFlowRun.
Trace scheduling and execution through runFlow, scheduleTasks, and executeTaskRun.
Inspect SQLTaskManager polling when tasks are not claimed or advanced.
Use the Task API or MCP documentation only when testing an external scheduling boundary.

Rules

Rule: Use this skill only for engine9 development: flow authoring, TaskWorker or SQLTaskManager debugging, and task-pipeline extension.

Rule: Every step must have a unique task_key and a unique name.

Rule: Do not reuse a worker method such as echo or query as the name of multiple tasks. Remote merge indexes by task_key, context_id, and label or name; duplicate names collide.

Rule: API consumers schedule existing flows and methods; they do not author JSON5 flow definitions through the Task API.

Rule: A flow for a specific account must carry that account's plugin identifiers on every plugin step. plugin_id is the installed plugin row id. assignee.bot_id is that row's remote_plugin_id. Load both from the account's installed plugins before writing the file. A package path is not a substitute. If those plugins cannot be loaded, stop and do not write the flow. A shared flow that is not bound to one account (for example identity-rebuild) names the package path; those ids differ per account.

Examples

An API integrator may schedule the built-in echo worker by using:

path: @engine9/plugins/e9workers:EchoWorker
method: echo

That request belongs to the Task API or MCP documentation. The flow definition and its unique task names belong to this developer skill.

Troubleshooting

Symptom	Check
One task overwrites another during merge	Duplicate `task_key`, `name`, or label
Flow run is created but does not advance	`runFlow`, scheduled task state, and SQLTaskManager polling
Worker task is never executed	`path`, `method`, task scheduling, and `executeTaskRun`
Account flow has plugin paths and no plugin ids	Load that account's plugins and set `plugin_id` and `assignee.bot_id` before writing the file
Unsure whether to use this skill	Use it only when editing or debugging implementation internals

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free