flow-skills

Agent skills for Flow, a bioinformatics platform built by Goodwright. This repository is a plugin marketplace; today it ships one plugin, flow-ai, which lets an AI agent query Flow's REST API — and upload data — on your behalf.

What flow-ai does

flow-ai is primarily a read-only skill that can also upload data to Flow: generic data files, demultiplexed samples, and multiplexed reads with an annotation sheet. With it, an agent can answer questions and run uploads like:

• "What pipelines are available on Flow?"
• "How many samples do I own?"
• "What was the last successful execution of the RNA-Seq pipeline on sample X, and what data files did it produce?"
• "Download the FASTQ for data file 67890."
• "Upload counts.tsv to Flow as a data file."
• "Upload a paired-end RNA-Seq sample with this metadata."
• "Upload these multiplexed reads with my annotation sheet."

See plugins/flow-ai/skills/flow-ai/SKILL.md for the current capabilities.

Getting a Flow API key (optional)

The skill works unauthenticated, but most resources on Flow are private, so an authenticated key dramatically broadens what you can ask about.

1. Sign in to Flow at https://app.flow.bio.

2. Open https://app.flow.bio/settings and go to the Account Management tab.

3. In the API Keys section, choose:

   • Key purpose: AI Agent (recommended for use with this skill).
   • Lifetime: how long the key should remain valid.

4. Click create, then copy the key immediately — it's shown only once.

5. Save it to ~/.config/flow/api-token with restrictive permissions (if on Windows see note further down):

   mkdir -p ~/.config/flow
   umask 077
   pbpaste > ~/.config/flow/api-token   # or paste manually
   chmod 600 ~/.config/flow/api-token

The skill checks for this file on every invocation. When present, the flowbio CLI reads it and authenticates every read (and upload); when absent, reads fall back to public/anonymous access. The skill never prints the token — the CLI reads the file itself, and the only commands that reference it directly (the pipeline-run and file-download curls) do so via $(< ~/.config/flow/api-token) inside a -H flag.

If on Windows

Click to expand

Add the token to your windows home folder like so:

  New-Item -ItemType Directory -Force "$env:USERPROFILE\.config\flow"
  [System.IO.File]::WriteAllText(
    "$env:USERPROFILE\.config\flow\api-token",
    "your-token-here"
  )

Install — Claude Code (recommended)

This repo is a Claude Code plugin marketplace. Inside Claude Code:

/plugin marketplace add goodwright/flow-skills
/plugin install flow-ai@flow-skills

To pick up new releases later, run /plugin marketplace update.

Install — other agents

The skill itself is just a directory of Markdown files following Anthropic's Agent Skill format. Any agent harness that loads skills from a directory can use it directly. Clone the repo and point your harness at plugins/flow-ai/skills/flow-ai/:

git clone https://github.com/goodwright/flow-skills.git
# Then either symlink or copy plugins/flow-ai/skills/flow-ai/ into wherever
# your agent loads skills from. For example, for Claude Code's standalone
# mode:
mkdir -p ~/.claude/skills
ln -s "$(pwd)/flow-skills/plugins/flow-ai/skills/flow-ai" ~/.claude/skills/flow-ai

For agents that consume SKILL.md directly (Codex, Gemini CLI, Copilot CLI, etc.), see your harness's documentation for the skill load path. The skill's contract is the YAML frontmatter in SKILL.md plus the supporting files it references — no harness-specific glue.

Reducing permission prompts

Flow reads run through the flowbio CLI's read-only api get command, which resolves your token itself. These calls carry no embedded secret and share a stable prefix, so — unlike the old token-substituting curl — they can be allowlisted through Claude Code's normal permissions.allow.

One wrinkle: the read recipes pipe the result through jq (flowbio api get … --json | jq '…'). Claude Code auto-approves a piped command only when every segment is allowlisted, and it does not offer a one-click "don't ask again" for multi-segment commands — so a read keeps prompting until you allowlist both the read command and jq. Add the entries that match how the CLI resolves on your machine (the skill prefers uvx, then pipx, then a flowbio already on your PATH) to .claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(flowbio api get:*)",
      "Bash(uvx --from flowbio==0.9.0 flowbio api get:*)",
      "Bash(pipx run --spec flowbio==0.9.0 flowbio api get:*)",
      "Bash(jq:*)"
    ]
  }
}

The entries must match the command the skill emits byte-for-byte — Claude Code prefix-matches the raw string, so the quoting has to agree (the skill emits the pinned spec unquoted, e.g. uvx --from flowbio==0.9.0 …).

Pipeline runs (POST) and file downloads still use curl and keep prompting; that is deliberate — a run changes remote state and is confirmation-gated, and a download can be large.

Versioning

The canonical version lives in plugins/flow-ai/.claude-plugin/plugin.json. Reads go through the flowbio CLI, so they no longer carry a flow-ai User-Agent; the string now survives only on the two curl remnants (the pipeline run and file download) as User-Agent: flow-ai/<version>, kept in lockstep so Flow's backend can attribute that traffic to a specific release. On each release, bump:

1. plugins/flow-ai/.claude-plugin/plugin.json#version
2. The User-Agent strings in examples.md (run + download recipes) and endpoints/pipelines.md (run recipe)
3. CHANGELOG.md

A pre-release sanity check:

grep -rn "flow-ai/[0-9]" plugins/flow-ai/skills/flow-ai/ | grep -v evals/ | grep -v 0.10.0

…should return nothing once everything is in lockstep. (The evals/ are excluded: they use a flow-ai/<version> placeholder and cite historical release numbers, neither of which tracks the current version.)

Contributing

Issues and PRs welcome at https://github.com/goodwright/flow-skills. For changes to the skill itself, also update an eval (or add a new one) that demonstrates the new behaviour.

License

MIT — © 2026 Goodwright.