Edit Flow
Create and edit pi-flows flows and agents from the main session. Use when the user wants to create a new flow, add or change an agent, or edit an existing flow/agent. Covers agent frontmatter, flow YAML, step types, model references, the flowagents and flowwrite tools, write locations, and how to fix validation errors.
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Edit Flow when an AI agent needs a reusable SKILL.md workflow for this job: Create and edit pi-flows flows and agents from the main session. Use when the user wants to create a new flow, add or change an agent, or edit an existing flow/agent. Covers agent frontmatter, flow YAML, step types, model references, the flowagents and flowwrite tools, write locations, and how to fix validation errors.
When not to use it
Skip Edit Flow when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/edit-flow # Save SKILL.md to ~/.claude/skills/edit-flow/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/edit-flow/SKILL.md. For a shared project, commit the folder at .claude/skills/edit-flow/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Edit Flow skill for this task: Clarify what the user wants the flow to do. Ask if it is unclear. Confirm any required inputs or files before making changes.
What supports this recommendation?
83/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 92/100
- Practical detail
- 92/100
- Source evidence
- 61/100
- Source signals
- 72/100
Model compatibility evidence
- claudeinferred
The skill text mentions Claude or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.
- chatgptinferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
- geminiinferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
- copilotinferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
- llamainferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
- perplexityinferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
- mistralinferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
- grokinferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# Edit Flow
You are creating and editing **pi-flows** flows and agents directly in this session. Two tools do the writing (both validate before writing and return diagnostics on failure):
- `flow_agents` — `op: "list"` returns the agent catalog; `op: "write"` validates and writes an agent `.md` to `.pi/flows/agents/<name>.md` (filename derived from the agent's frontmatter `name`). - `flow_write` — `namespace` (default `custom`), `name`, `content`. Validates and writes a flow to `.pi/flows/flows/<namespace>/<name>.yaml`, which auto-registers as the `/<namespace>:<name>` command.
These tools derive their write locations from the discovery convention — there is **no raw `path`**. Writing to a name that already exists overwrites it (that is how you edit).
> The edit-flow tools are **off by default**. They are active only when `flows.editFlow: true` is set in `.pi/settings.json` (project, when trusted) or `~/.pi/agent/settings.json` (global). If `flow_agents`/`flow_write` are not available, tell the user to enable that setting and restart the session.
## Workflow
1. Clarify what the user wants the flow to do. Ask if it is unclear. 2. Call `flow_agents` with `op: "list"` to see existing agents and their `inputs`, `outputs`, and `source_type`. Reuse `built-in`/`local` agents where they fit. 3. For each role not already covered, author a purpose-built agent with `flow_agents` `op: "write"`. Do not repurpose infrastructure agents (`flow-decision`, `project-context-reader`) for unrelated tasks. 4. Author the flow with `flow_write`. Wire every declared input. Fix any validation diagnostics and retry. 5. Tell the user the resulting command name (`/<namespace>:<name>`).
**Editing** an existing flow/agent = `read` the current file, change it, then write it back with the same tool and the same name/namespace.
## Agent files (`.md`)
YAML frontmatter + Markdown body (the system prompt).
```markdown --- name: code-reviewer description: Reviews source code for quality and correctness model: @coding thinking: medium tools: read, grep, find inputs: - research_context outputs: - name: findings description: Categorized issues found - name: verdict description: "pass" or "fail" access: read: - "src/**" write: - "src/**" bash: deny: - "rm -rf *" card: label: "Reviewer" metric: "default" architect: use_when: "User wants code reviewed for quality" produces: "A findings report and a pass/fail verdict" depends_on: "An implementer must have produced code" domain: "review" ---
# System Prompt
You are a code reviewer. Task: ${{task}} Context: ${{input.research_context}} ```
| Field | Required | Notes | |-------|----------|-------| | `name` | Yes | Unique. Filename = `<name>.md`. Referenced as `agent: <name>` in steps. | | `description` | Yes | One line. Shown in catalog. | | `model` | Yes | See **Model references**. | | `tools` | Yes | Comma-separated. Guard blocks anything not listed. Standard: `read, write, edit, grep, find, ls, bash, ask_user, skill_read`. | | `thinking` | No | `off`/`minimal`/`low`/`medium`/`high`/`xhigh`. Overrides any `:level` suffix in `model`. | | `skills` | No | Comma-separated skill names injected into the prompt. | | `inputs` | No | Names → `${{input.NAME}}` in the prompt. Flow step must wire each one. | | `outputs` | No | Names (or `{name, description}` objects). Become `finish` parameters and `${{result.STEP.NAME}}` downstream. | | `interactive` | No | `true` allows mid-task UI prompts. Default `false`. | | `output` | No | Output file hint (display only). | | `access` | No | `read`/`write` glob allowlists; `bash.deny` command patterns. `*` = segment, `**` = any depth. | | `card` | No | `label`, `metric` (`default`/`files`/`tests`/custom), `role`. | | `architect` | No | `use_when`/`produces`/`depends_on`/`domain` metadata surfaced in `flow_agents` `op: list`. |
## Model references
The `model:` field accepts three forms. **Prefer `@role`.** Use the other two when a specific model is required regardless of role config, or when the user explicitly asks for a non-role model.
| Form | Example | When | |------|---------|------| | `@role` (preferred) | `model: @coding` | Default. Resolves via the active role→model map (`/roles`). Built-in roles: `@planning`, `@coding`, `@fast`, `@architect`. | | `provider/model[:thinking]` | `model: anthropic/claude-haiku-4-5:high` | A specific provider+model is required; optional `:thinking` suffix sets the thinking level. | | bare `model-id` | `model: claude-haiku-4-5` | A specific model id with no provider qualifier; thinking comes from the `thinking:` field or none. |
A `thinking:` field always overrides any `:thinking` suffix in `model`.
## Flow files (`.yaml`)
```yaml name: my-flow # REQUIRED description: What it does # REQUIRED max_concurrent: 3 # optional (default 4) task_required: true # optional — prompt for task if invoked with no args task_prompt: "Task:" # optional
steps: - id: research agent: code-reviewer task: Review ${{task}} ```
`name` is the frontmatter name; the command name comes from the on-disk location (`namespace`/`name` you pass to `flow_write`). Every step needs a unique `id`. Step `type` is usually inferred from which fields are present; set `type:` explicitly when ambiguous.
### Step types
1. **agent** — dispatch an agent. ```yaml - id: impl agent: implementer task: Implement ${{task}} blockedBy: [research] inputs: ctx: ${{result.research.summary}} on_complete: verify # optional cross-segment jump on_error: handler # optional ``` 2. **fork** — user (or `agent:` in autonomous mode) picks a branch. ```yaml - id: choose type: fork question: Which strategy? options: [Fast, Full] branches: { Fast: fast-impl, Full: full-impl } agent: flow-decision # autonomous-mode decider allowCustom: false multiSelect: false ``` Branch keys must match `options` exactly. 3. **conditional** — presence/absence of a result field. ```yaml - id: has-gaps type: conditional check: research.artifacts # stepId.field present: gap-filler absent: finalize ``` 4. **agent-decision** — agent calls `finish({ branch })` to choose. ```yaml - id: complexity type: agent-decision agent: analyzer task: Simple or complex? branches: { simple: quick, complex: thorough } ``` 5. **agent-loop-decision** — loop back or exit. ```yaml - id: should-fix type: agent-loop-decision agent: flow-decision task: Iteration ${{loop.should-fix.iteration}}/${{loop.should-fix.max}}. ${{result.verify.summary}} loop_target: fixer # jump back exit_target: done # continue forward max_iterations: 3 ``` 6. **flow-ref** — delegate to another flow file. ```yaml - id: sub type: flow-ref path: "project/changes/*/exec.yaml" # glob ok on_complete: verify ```
### Template variables
Expanded in `task`, `inputs` values, and `question`. Not validated — a typo silently becomes empty string.
- `${{task}}` — the user task. - `${{input.NAME}}` — input wired into this step. - `${{result.STEP_ID.status|summary|artifacts|files|fullOutput|OUTPUTNAME}}` — `STEP_ID` is the step `id`, not the agent name. - `${{loop.STEP_ID.iteration|max}}` — loop counters.
Wire data between steps via `inputs:` (agent declares names in frontmatter, step supplies values). Prefix an input value with `file://` to inject file content verbatim; that file's producer step must be in `blockedBy`.
## Write locations (discovery)
| Content | Tool | Lands at | |---------|------|----------| | Agent | `flow_agents` `op: write` | `.pi/flows/agents/<name>.md` | | Flow | `flow_write` | `.pi/flows/flows/<namespace>/<name>.yaml` → `/<namespace>:<name>` |
Project-local definitions (`.pi/flows/`) override package and built-in ones.
## Fixing validation errors
Both tools validate before writing. On failure they return `{ written: false, diagnostics: [...] }` and write nothing. Read each diagnostic's `message` and `suggestion`, fix the content, and call the tool again. Common cases:
- **Missing required field** (`name`, `description`, `model`, `tools` for agents; `name`, `description` for flows) → add it. - **"Agent not in catalog"** → the flow references an agent that does not exist. Create it with `flow_agents` `op: write`, then retry `flow_write`. - **Unwired declared input** → add the missing key to the step's `inputs:` block. - **Unknown tool in `tools:`** → use a valid tool name (see the standard list above) or an extension-registered tool name. - **Invalid YAML** → fix indentation/quoting; re-validate.
Intended uses
- Clarify what the user wants the flow to do. Ask if it is unclear.
- Call flowagents with op: "list" to see existing agents and their inputs, outputs, and sourcetype. Reuse built-in/local agents where they fit.
- For each role not already covered, author a purpose-built agent with flowagents op: "write". Do not repurpose infrastructure agents (flow-decision, project-context-reader) for unrelated tasks.
- Author the flow with flowwrite. Wire every declared input. Fix any validation diagnostics and retry.
- Tell the user the resulting command name (/<namespace>:<name>).
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.