flowstate-plugin-author
/flowstate-plugin-author
Use when asked to write or change a Flowstate plugin (a task provider, the executable flowstate-plugin-<name>): decide if a plugin is needed, define the schema in Protobuf, test and rehearse it locally.
- Author
- picatz ↗
- Repository
- flowstate ↗
- Licence
- MIT
- Last repository change
- 23.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 3
No signals detected. Repository changed on 23.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use when asked to write or change a Flowstate plugin (a task provider, the executable flowstate-plugin-<name>): decide if a plugin is needed, define the schema in Protobuf, test and rehearse it locally.
Original author description
Use when asked to write or change a Flowstate plugin (a task provider, the executable flowstate-plugin-<name>): decide if a plugin is needed, define the schema in Protobuf, test and rehearse it locally.
How it works
- Decide first
- Build it the right way
- Secrets and errors
- Bound what you fetch
- Validate, test, run locally first
- Before you finish
SKILL.md preview
---
name: flowstate-plugin-author
description: Use when asked to write or change a Flowstate plugin (a task provider, the executable flowstate-plugin-<name>): decide if a plugin is needed, define the schema in Protobuf, test and rehearse it locally.
---
# Authoring a Flowstate plugin
A plugin is a separate executable a worker launches; its tasks appear to a
Flowfile as `<plugin>.<task>:`. The full walkthrough is
[docs/PLUGINS.md](https://github.com/picatz/flowstate/blob/main/docs/PLUGINS.md);
the worked example is
[flowstate-plugin-example](https://github.com/picatz/flowstate/tree/main/pkg/flowstate/v1/plugin/examples/flowstate-plugin-example),
and [examples/plugins](https://github.com/picatz/flowstate/tree/main/examples/plugins)
holds Flowfiles that use plugin tasks. Read them before writing code. Later
mentions of PLUGINS.md mean that page.
## Decide first
- Run `flow tasks`. The built-ins are `exec`, `http`, and `log`; `flow tasks
http` shows the inputs `http` takes (its response cap and egress come from
operator policy). An API reachable with `http` is a
Flowfile, not a plugin.
- Reuse a Flowfile with `call:` when the logic is a composition of steps.
- Write a plugin only for behavior a Flowfile cannot express: a protocol that is
not an HTTP fetch, a client library, or a secrets backend.
## Build it the right way
- Name the binary `flowstate-plugin-<name>`; discovery ignores anything else,
and the suffix is the qualifier a Flowfile writes.
- Use `sdk.Main(sdk.Plugin{...})` from `pkg/flowstate/v1/plugin/sdk`. Set
`Version` and `Description` on `sdk.Plugin`, and a one-line `Summary` on every
`Task`.
- Define the schema once, in Protobuf. Set `Input:` and `Output:` to the
generated messages, decode with `sdk.DecodeInputs`, return `sdk.EncodeOutputs`.
Never hand-write a second struct for the same shape. A task with no
descriptors validates nothing: a misspelled input passes `flow validate`.
- Generate with `go tool buf generate proto`, using `protoc-gen-go` and `protoc-gen-flowstate-doc` (see
the `buf.gen.yaml` in PLUGINS.md; the second carries field comments to
editors). Regenerate, never hand-edit `*.pb.go`.
- Put bounds in the schema with standard protovalidate rules (`string.max_len`,
`repeated.max_items`, `in`, `required`); the host enforces them at
`flow validate`.
- Plugin `cel` rules (`(buf.validate.field).cel` and the message and predefined
forms) are stripped host-side, so plugin CEL can never be a `flow validate`
contract. Put any cross-field or computed check in the plugin's own process.
- Print nothing to stdout before the SDK serves; it corrupts the handshake. Log
to stderr or with `sdk.WithLogger`.
- `Fn` runs concurrently. Guard package-level state with a mutex, `sync.Once`,
or an atomic. Build the manifest from constants, never from the environment
or a clock: a relaunched plugin that describes itself differently is refused.
## Secrets and errors
- Secrets stay references until the point of use. An input that accepts one
carries a `(flowstate.v1.input).secret` claim in the `.proto`
(`SECRET_WHOLE_VALUE`, or `SECRET_REQUIRED` for one that must be a reference),
and the task's `SecretInputs` / `RequiredSecretInputs` must list exactly the
same fields: the host compares the two and refuses a plugin that disagrees.
`SECRET_NESTED` is refused. The host resolves the reference worker-side and
`DecodeInputs` hands your function the resolved string.
- A credential (`Credentials:` on the plugin plus `(flowstate.v1.input).credential`
on the input) is a layer on top of that, not a replacement: the claim implies
`SECRET_REQUIRED`, so the input still appears in both task lists, and it
lets an author bind it once under `plugins:`.
- Never put a secret, token, or credential-bearing backend message in a returned
error, a log line, stderr, or a health message: errors are written to durable
workflow history.
- Return errors through the constructors (`sdk.InvalidInput`, `sdk.Failed`,
`sdk.Unavailable`, `sdk.UnavailableAfter`, `sdk.OutcomeUnknown`, ...). Only
`Unavailable` is retried; pick the one that is true.
## Bound what you fetch
- Reach the network only through `sdk.HTTPClient()`. It applies the operator's
egress policy and `max_response_bytes`; do not build your own `http.Client`.
- Call `sdk.WithCredentials(ctx)` when a secret travels somewhere the SDK cannot
see (a query string, a custom header, a body).
- HTTP with its own size or time bound (a packfile, a paginated listing) uses
`sdk.HTTPClientWithBounds(maxResponseBytes, timeout)`. Any other dial
(a custom transport or protocol-native client) goes through the egress
policy from `sdk.EgressPolicy()` or `sdk.EgressPolicyWithBounds(...)`; never
a raw `net.Dial`. The bounds change what is sized, never what may be reached.
- Cap every list, page count, and read a remote party controls.
## Validate, test, run locally first
```sh
go build -o ./bin/flowstate-plugin-<name> . # the name is not optional
flow plugins --plugin-dir ./bin # launches it; shows tasks, inputs, outputs
flow tasks --plugin-dir ./bin <name>.<task> # the task in full, with a step to copy
flow validate --plugin-dir ./bin workflow.yaml
flow plugins --plugin-dir ./bin -o json > plugins.lock.json
flow test --plugin-catalog plugins.lock.json workflow.test.yaml # plugin tasks stubbed
flow run local workflow.yaml --plugin-dir ./bin --secret-env NAME --auth-policy auth.yaml
```
- `flow plugins` surfaces a manifest typo that stops a plugin at startup; add
`--verbose` to read the plugin's own message. Run it on every build.
- A secret passed to an input not declared secret passes `flow validate` and is
refused at run time, so cover it with a `flow run local` leg.
- In Go, test with `pkg/flowstate/v1/plugin/plugintest`: `Build`, `Launch`,
`Run`/`Call`, then `s.Conform(t)`. Put it in its own package that imports
neither `main` nor `gen/`, and skip it under `-short`. Test a refused input
and a failure kind, not only the happy path, and assert that a secret value
appears in no output and no error.
- `flow validate --plugin-catalog plugins.lock.json workflow.yaml` checks a file
against the saved catalog without launching a plugin.
## Before you finish
- [ ] A built-in task or a `call:` could not do the job.
- [ ] The schema is Protobuf, generated, and used for `Input` and `Output`.
- [ ] Every task has a summary, and every field a comment.
- [ ] No secret in any error, log, or output; secret inputs declared.
- [ ] External responses and lists are bounded; network goes through the SDK.
- [ ] No rule depends on plugin `cel`.
- [ ] `flow plugins`, `flow validate`, and `flow run local` ran with `--plugin-dir`.
- [ ] `plugintest` with `Conform` passes, including a negative case.
Versions
The database has no other skills named flowstate-plugin-author.
Database snapshot: 13.11.2026 · package version 5499e83e5712 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90flowstate-ship
Use when asked to land, ship, or merge a Flowstate pull request, or to take one through the exact-head review, disposition, shipcheck, and manual-merge gates that an autonomous merge requires. - 95flowstate-verify
Use when choosing, running, or reporting Flowstate verification (a bounded targeted test, the diff-scoped gate, or the full CI-parity rehearsal) before a handoff, a pull request, or a merge. - 100plugin-development
Create and run NetAlertX plugins. Use this when asked to create a plugin, run a plugin, test a plugin, or develop plugin functionality. - 100fh2-plugin-dev
司空(FH2,即 FlightHub 2)插件开发技能。用户要在司空里加插件、改插件、调试或打包插件时使用:扩展点、插件界面、前端清单、后端 Handler/事件/流程、生成类型、本地调试页面联调。用户提到 fh2-plugin 命令、能力工程、上传包,或直接描述「给驾驶舱加个工具栏按钮」「做个导出 PDF 的插件」「司空2 里加个面板」「大疆司空插件」这类需求时也用。只问概念、不要求改代码时不要用;操作对象不是插件工程(改宿主自身页面、纯运维)时不要用。 - 100writing-plugins
Use when writing, scaffolding, or modifying Nuclear plugins. Covers plugin structure, manifest, entry point, provider types, available APIs, and publishing. Trigger phrases include "create a plugin", "write a plugin", "plugin scaffold", "streaming provider", "metadata provider". - 95netalertx-plugin-run-development
Create and run NetAlertX plugins. Use this when asked to create plugin, run plugin, test plugin, plugin development, or execute plugin script.