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, it attaches Authorization: Bearer … to every request. When absent, it proceeds unauthenticated. The skill never prints the token — it's referenced only via $(< ~/.config/flow/api-token) inside a curl -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

Every authenticated Flow read injects your token with the command substitution $(< ~/.config/flow/api-token). Claude Code treats $(...) as a security boundary, so a permissions.allow rule can't silence these calls and the "don't ask again" option is never offered — you get prompted on every read.

flow-ai ships an opt-in PreToolUse hook that auto-approves those reads. It is strictly read-only: it only matches a curl that starts with the flow-ai User-Agent, uses --get, and targets flow.bio (or your FLOW_API_URL). Pipeline runs (POST), uploads (which go through the flowbio CLI), commands that merely contain a Flow read, and any other host all keep prompting exactly as before.

The hook does nothing until you opt in. Set FLOW_AI_AUTO_APPROVE_READS=1, either exported in the shell that launches Claude Code:

export FLOW_AI_AUTO_APPROVE_READS=1

or via an "env" block in your .claude/settings.json:

{
  "env": { "FLOW_AI_AUTO_APPROVE_READS": "1" }
}

Activation caveat: Claude Code snapshots hooks at session start. After installing the plugin or setting the env var, you must restart Claude Code or run /reload-plugins — the hook does not activate in the session where it was enabled. This is the easiest step to miss.

To verify: after restarting, run any Flow read (e.g. "what pipelines are on Flow?") and confirm no prompt appears; then confirm a pipeline run still prompts.

Versioning

The canonical version lives in plugins/flow-ai/.claude-plugin/plugin.json. The User-Agent: flow-ai/<version> string in SKILL.md is kept in lockstep so Flow's backend can attribute traffic to a specific release. On each release, bump:

1. plugins/flow-ai/.claude-plugin/plugin.json#version
2. The User-Agent strings in SKILL.md and examples.md
3. CHANGELOG.md

A pre-release sanity check:

grep -rn "flow-ai/" plugins/flow-ai/skills/flow-ai/ | grep -v 0.2.0

…should return nothing once everything is in lockstep.

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.