Skip to content
Skills Library
Programming · Building & coding

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.

Repository
flowstate ↗
Licence
MIT
Last repository change
23.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 23.10.2026, without references to retired models or APIs.

Licence

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

  1. Decide first
  2. Build it the right way
  3. Secrets and errors
  4. Bound what you fetch
  5. Validate, test, run locally first
  6. Before you finish
Original SKILL.md headings · 116 lines, 944 words
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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.