skills/skills/flow-package-author/SKILL.md

name	description
flow-package-author	Use when creating or updating portable Codex flow packages, including flow.toml manifests, generic FlowEvent contracts, JSON Schema payload validation, exec snippets, fixtures, and installed/source flow bundle layout.

Flow Package Author

Use this skill for the mechanics of packaging arbitrary flows. It does not define project-specific release, remote, mirror, credential, or publishing policy.

Core Rules

• Use flow naming: flow bundle, flow.toml, flow step, flow event, FLOW_RESULT.
• Keep the event envelope generic: id, type, optional source, optional occurredAt, receivedAt, and payload.
• Put domain-specific payload shape in schemas/*.schema.json; do not bake repo, package, release, or git fields into the core event envelope.
• If a flow needs project-specific behavior, declare it in guidance.skills and read those skills/docs before writing push, publish, mirror, branch-protection, or credential behavior.
• Flow packages should be idempotent by event.id.

Layout

Packageable source layout:

flows/<name>/
  flow.toml
  schemas/*.schema.json
  exec/*.js
  exec/*.code-mode.js
  README.md
  fixtures/
  tests/

Installed operational layout:

.codex/flows/<name>/
  flow.toml
  schemas/*.schema.json
  exec/

Manifest

flow.toml should define:

name = "example-flow"
version = 1
description = "Short purpose."

[guidance]
skills = []

[config]
# Package-specific, portable settings. Prefer env var names over secrets.
commit = false

[[steps]]
name = "step-name"
runner = "bun" # or "code-mode"
script = "exec/step-name.js"
timeout_ms = 300000

[steps.trigger]
type = "example.event"
schema = "schemas/example-event.schema.json"

Result Contract

Every step must emit exactly one line:

FLOW_RESULT {"status":"completed","message":"...","artifacts":{},"next":[]}

Valid statuses are skipped, completed, changed, needs_intervention, blocked, and failed.

Authoring Checklist

• Add a schema for every nontrivial event payload.
• Add at least one fixture event for each trigger.
• Keep exec snippets relative to the flow bundle.
• Put portable defaults and environment variable names in [config]; do not put secret values in the manifest.
• Avoid hidden local handled-state as truth; prefer event ids, durable artifacts, remote refs, or backend run records.
• Keep org-specific instructions out of this skill and inside the flow package README or referenced guidance skills.