flow-setup skill
✓ VerifiedInitializes or aligns Flow repository structures, migrates legacy agent layouts, and scaffolds OKF v0.2 knowledge bundles and domain-specific skills.
- GitHub stars
- 20
- Files
- 1
- Last commit
- Nov 8, 2026
- License
- Apache-2.0
- Allowed tools
- —
What does the flow-setup skill do?
flow-setup initializes or aligns Flow repository structures, migrates legacy agent layouts, and scaffolds OKF v0.2 knowledge bundles and domain-specific skills.
Summary generated from the skill's SKILL.md.
About the flow-setup skill
Setting up or aligning Flow repository structures is what this skill enables for developers managing agentic workflows. It automates the transition from legacy layouts like .beads/ or .agents/specs/ into the standardized OKF v0.2 format. When an agent loads this skill, it can perform environment detection, inventory existing files, and probe host binaries such as uv, python3, cargo, or npm to ensure the toolchain is correctly identified.
The process produces a complete .agents/ directory containing organized knowledge bundles, domain-specific skills, and specialized subagents. It scaffolds core context chapters including product guidelines and tech stacks, while ensuring all knowledge files use proper citations and footnotes. Developers can choose to track these files in Git as shared assets or keep them local-only. The skill concludes by generating a setup state file and updating project documentation like AGENTS.md to reflect the new architecture.
What an agent can do with it
- 1Bootstrap project-local hooksIntegrate session start and stop hooks into local IDE settings like Claude or Cursor.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the flow-setup skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the flow-setup skill in Plugin
/plugin marketplace add cofin/flow /plugin install flow@flow-marketplace
Install the flow-setup skill in Claude Code
~/.claude/skills/flow-setup/SKILL.md
$ npx degit cofin/flow/skills/flow-setup ~/.claude/skills/flow-setupInstall the flow-setup skill in Claude Code (project)
.claude/skills/flow-setup/SKILL.md
$ npx degit cofin/flow/skills/flow-setup .claude/skills/flow-setupInstall the flow-setup skill in Codex
~/.agents/skills/flow-setup/SKILL.md
$ npx degit cofin/flow/skills/flow-setup ~/.agents/skills/flow-setupInstall the flow-setup skill in Gemini CLI
~/.gemini/skills/flow-setup/SKILL.md
$ npx degit cofin/flow/skills/flow-setup ~/.gemini/skills/flow-setupInstall the flow-setup skill in Claude.ai
npx degit cofin/flow/skills/flow-setup flow-setup && zip -r flow-setup.zip flow-setup # claude.ai → Customize → Skills → + → Create skill → Upload a skill → flow-setup.zip
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablecofin/flow/skills/flow-setup is public and reachablegithub.com/cofin/flow/tree/HEAD/skills/flow-setup ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-08github.com/cofin/flow/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/cofin/flow/blob/HEAD/skills/flow-setup/SKILL.md ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/cofin/flow/blob/HEAD/skills/flow-setup/SKILL.md ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 46 linesgithub.com/cofin/flow/blob/HEAD/skills/flow-setup/SKILL.md ↗Pass
SKILL.md
View on GitHubFlow Setup
Trigger
Use for /flow:setup. Follow ../flow/references/setup.md.
Workflow
- Environment Detection, Brownfield Alignment, & Sharded Toolchain Discovery:
- Inspect
.agents/setup-state.jsonand.agents/bundles/index.md. If.agents/already exists, offer Align & True-Up (Recommended), Full Re-Setup, or Exit. - In alignment/brownfield mode, inventory legacy layouts (
.beads/,.agents/specs/,.agents/tracks/,.agents/transactions/, flatknowledge/patterns.md, sibling PRD child specs withparent_prd:if desired, un-promotedbundles/research/, legacy.agents/skills/flow-memory-keeper/), ensure subdirectoryindex.mdfiles andlog.mdcarry zero YAML frontmatter and zero standalone---body rules, and migrate active work without data loss after user confirmation. - Probe installed host binaries (
uv,python3,cargo,go,bun,pnpm,npm,make,just,pwsh,powershell) alongside repository manifests. Fan out parallel read-only@researchersubsystem Scouts (type_name="self"withagents/researcher.mdon Google Antigravity;model="inherit").
- Inspect
- Scaffold Core Context Chapters & Rich OKF v0.2 Bundle (
.agents/bundles/):- Initialize
.agents/bundles/index.md(okf_version: "0.2") and frontmatter-free.agents/bundles/log.md,product/index.md,knowledge/index.md,research/index.md, andspecs/index.md. - Create Flow's core context chapters with bounded
<= 40-line<!-- truth: start -->blocks and zero body---separators:product/product.md,product/product-guidelines.md,product/tech-stack.md, andknowledge/workflow.md(populated with verified host commands from../../templates/agent/workflow.md). - Synthesize evidence-backed nested chapters across
knowledge/{architecture,patterns,domains,testing,gotchas,decisions}/(via parallel domain synthesis subagents when>= 2domains exist) withsources: [{ id, resource, title }]+[^id]:footnotes andverified: [{ by, at }].
- Initialize
- Seed Baseline Engineering Disciplines & Stack-Specific Project-Local Skills (
.agents/skills/) and Subagents (.agents/agents/):- Follow
../multi-harness-plugins/SKILL.mdand../flow-docs/references/agent-context.md. - Embed baseline engineering rules into the repository's knowledge and skill set: Deep-Module & Seam Design, Active Domain Modeling & ADR Filter, Public-Seam Vertical-Slice TDD & Hypothesis-Driven Bug Diagnosis, and Present-Tense Cold-Reader Prose & Documentation Accuracy.
- Generate consolidated domain skills (
.agents/skills/<domain>/SKILL.md<= 200lines +references/*.md), domain review capability skills (.agents/skills/review-<domain>/SKILL.md+references/checklist.md+references/false-positive-suppressions.md),.agents/skills/index.md, and paired project-local subagents (.agents/agents/<domain>-reviewer.mdand.agents/agents/<domain>-specialist.mdwith H1#headings,mainAgent: false,subagent: true,model: inherit, andcommandExecutionPolicy: sandbox).
- Follow
- Cross-Harness Policy &
StopHook Bootstrap,AGENTS.md, &.agents/setup-state.json:- Ask once via
structured-choice-v1whether.agents/isshared(tracked in Git, Recommended) orlocal-only(stealth mode via.git/info/exclude). - Offer opt-in non-destructive harness policy and project-local
SessionStart+Stophook merges (.claude/settings.local.jsonwith backup,.cursor/hooks.json,opencode.json), update rootAGENTS.md(preserving<!-- project-customization: start -->blocks), and write.agents/setup-state.json.
- Ask once via
Guardrails
- Never copy Flow's global plugin skills (
flow,flow-*,okf,debloat,multi-harness-plugins) or legacyflow-memory-keeperinto.agents/skills/. - Every materialized knowledge chapter must cite real repository paths (
path/to/file::Symbol) insources:and[^id]footnotes. - Preserve existing custom content inside
<!-- project-customization: start -->and<!-- truth: start -->blocks during alignment.
Output
Return the initialized or aligned .agents/bundles/ tree, generated .agents/skills/ and .agents/agents/ inventory, verified host commands, and next command (/flow:spec or /flow:prd).
Validation
Confirm root index.md declares okf_version: "0.2", all links in index.md and .agents/skills/index.md resolve on disk, every non-reserved .md file has valid OKF frontmatter, and .agents/setup-state.json records setup_status: "complete".
Files in this skill
1flow-setup skill questions
How do I install the flow-setup skill in Claude Code?
Run npx degit cofin/flow/skills/flow-setup ~/.claude/skills/flow-setup. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the flow-setup skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
Can I choose whether the .agents/ directory is shared or local?
Yes, the tool asks via a structured choice whether the directory should be shared (tracked in Git) or local-only (using .git/info/exclude).
Does the setup process preserve my existing custom content?
Yes, it is designed to preserve existing custom content within specific truth and project-customization blocks during alignment.