flow

Decision 0017 · Accepted

Coexist with Claude Code
built-in skills

Claude Code ships its own skills and commands alongside any installed Flow skills. Several overlap with the Flow catalog: Flow skill Claude Code counterpart Difference simplify /simplify Same name.

Status
Accepted
Built from:
da88c48

Status: Accepted (2026-10-27). Superseded in part by 0062 (delegate to built-ins instead of coexisting). Related: 0004, 0006, 0009, 0013.

Context

Claude Code ships its own skills and commands alongside any installed Flow skills. Several overlap with the Flow catalog:

Flow skill Claude Code counterpart Difference
simplify /simplify Same name. Flow refactors for clarity with exact behavior; Claude Code reviews changed code and applies cleanups.
review /code-review Flow also checks intent and root-context alignment; Claude Code hunts correctness bugs at effort levels.
security /security-review Flow hardens untrusted-input handling; Claude Code audits branch changes.
flow, start /init, memory /init writes CLAUDE.md; Flow keeps context in PRODUCT.md, DESIGN.md, GLOSSARY.md, ARCHITECTURE.md and never edits adopter instruction files.
handoff Automatic compaction Compaction shrinks the current session; handoff writes a document for a fresh agent.
to-tasks Session task list The task list is ephemeral; to-tasks produces durable vertical slices.

Flow skills except flow set disable-model-invocation: true, while Claude Code's built-ins may be model-invoked. Plain requests such as "review this" therefore tend to reach the built-in, not Flow.

Most other Claude skills do not overlap: document formats, artifacts, browser and simulator control, scheduling, and API reference sit outside Flow's scope. Flow has no Claude Code counterpart for product discovery, specs, decision records, or shared language.

Decision

  • Flow owns intent and durable artifacts: root context, specs, decisions, glossary, and product discovery. Host skills own execution and output formats. Using both is supported.
  • Keep the Flow simplify name. Flow is agent-agnostic (0004); one host's built-in does not justify renaming a portable skill. Document the collision instead.
  • Keep overlapping Flow skills (review, security, handoff, to-tasks) because their contracts differ from the host counterparts. Users choose per task.
  • In Claude Code projects, root context files remain the single home for product facts. CLAUDE.md and host memory should point to them rather than restate them.
  • Skill bodies stay vendor-neutral. Host-specific guidance lives in agent compatibility.

Rationale

Renaming or dropping skills for one host would fragment the portable catalog. The overlaps are about different contracts, not duplicated behavior, so documentation resolves the confusion at lower cost. Duplicated project context across CLAUDE.md and root docs would violate one authoritative home.

Alternatives

  • Rename Flow simplify (for example clarify). Removes the name clash but churns every host for a Claude Code–specific issue. Revisit if live verification shows /simplify resolving to the wrong skill.
  • Drop overlapping Flow skills in favor of built-ins. Loses intent alignment and portability to other hosts.

Consequences

  • Agent compatibility gains a Claude Code section covering the name clash and overlaps.
  • In Claude Code 2.1.308 an installed Flow simplify shadows the built-in /simplify (live run). Adopters who prefer the built-in can remove the Flow skill.

Jump to, or try a question