ccwf-cli skill
Use the ccwf CLI to render, validate, preview, export, or execute cc-wf-studio workflow JSON files from the terminal.
- GitHub stars
- 5,454
- Files
- 1
- Last commit
- Oct 7, 2026
- License
- —
- Allowed tools
- 3
What does the ccwf-cli skill do?
ccwf-cli uses the ccwf CLI to render, validate, preview, export, or execute cc-wf-studio workflow JSON files from the terminal.
Summary generated from the skill's SKILL.md.
About the ccwf-cli skill
Managing and executing AI-agent workflows from the terminal is what ccwf-cli enables for developers using cc-wf-studio. This tool processes workflow JSON files, typically found in .vscode/workflows/, to transform them into actionable agent instructions. It provides a command-line interface to validate schemas, render Markdown with Mermaid diagrams, and preview workflows in a browser-based viewer.
Developers can use this skill to convert workflow files into specific Agent Skill files for various platforms including Claude Code, Cursor, Gemini, and Copilot. It supports direct execution of workflows via the run command and allows for AI-driven editing by running an in-process MCP server. Whether you need to check if a hand-edited JSON file is valid or want to materialize a workflow as a skill for a specific agent, this CLI provides the necessary subcommands to bridge the gap between raw JSON and functional agent capabilities.
What an agent can do with it
- 1Validate workflow JSON schemaCheck if a workflow file is correctly formatted and free of errors before running it.
- 2Convert workflows to agent skillsMaterialize a JSON workflow into specific skill files for agents like Cursor or Gemini.
- 3Execute workflows directlyRun a workflow and optionally launch the Claude Code binary to start execution immediately.
- 4Enable AI-driven workflow editingRun an MCP server to allow an AI client to read and modify workflow files through specialized tools.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the ccwf-cli 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 ccwf-cli skill in Claude Code
~/.claude/skills/ccwf-cli/SKILL.md
$ npx degit breaking-brake/cc-wf-studio/packages/cli/skills/ccwf-cli ~/.claude/skills/ccwf-cliInstall the ccwf-cli skill in Claude Code (project)
.claude/skills/ccwf-cli/SKILL.md
$ npx degit breaking-brake/cc-wf-studio/packages/cli/skills/ccwf-cli .claude/skills/ccwf-cliInstall the ccwf-cli skill in Codex
~/.agents/skills/ccwf-cli/SKILL.md
$ npx degit breaking-brake/cc-wf-studio/packages/cli/skills/ccwf-cli ~/.agents/skills/ccwf-cliInstall the ccwf-cli skill in Gemini CLI
~/.gemini/skills/ccwf-cli/SKILL.md
$ npx degit breaking-brake/cc-wf-studio/packages/cli/skills/ccwf-cli ~/.gemini/skills/ccwf-cliInstall the ccwf-cli skill in Claude.ai
npx degit breaking-brake/cc-wf-studio/packages/cli/skills/ccwf-cli ccwf-cli && zip -r ccwf-cli.zip ccwf-cli # claude.ai → Customize → Skills → + → Create skill → Upload a skill → ccwf-cli.zip
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A skill needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablebreaking-brake/cc-wf-studio/packages/cli/skills/ccwf-cli is public and reachablegithub.com/breaking-brake/cc-wf-studio/tree/HEAD/packages/cl ↗Pass
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit 2026-10-07github.com/breaking-brake/cc-wf-studio/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/breaking-brake/cc-wf-studio/blob/HEAD/packages/cl ↗Pass
- Pre-approved tools are scopedPre-approved: Bash(ccwf:*), Bash(npx, @cc-wf-studio/cli:*)github.com/breaking-brake/cc-wf-studio/blob/HEAD/packages/cl ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 211 linesgithub.com/breaking-brake/cc-wf-studio/blob/HEAD/packages/cl ↗Pass
SKILL.md
View on GitHubccwf CLI
ccwf is the command-line entry into cc-wf-studio — a visual AI-agent workflow tool. It treats .vscode/workflows/*.json workflow files as inputs and lets you render them as Markdown, validate the schema, open them in a browser-based viewer, convert them into Agent Skills, or execute them. The same workflow JSON also drives the VSCode extension and an MCP server, so you can pick whichever interface fits the situation.
This Skill teaches Claude how to recognise when ccwf is the right answer and which subcommand to reach for. The subcommands and flags listed here are the source of truth — if behaviour seems off, check ccwf <subcommand> --help first.
Prerequisites
Confirm ccwf is available before running any other subcommand:
ccwf --version
If ccwf is not on PATH:
- Preferred: install globally —
npm install -g @cc-wf-studio/cli - Without install: prefix every command with
npx @cc-wf-studio/cli(e.g.npx @cc-wf-studio/cli render <file>) - In a project:
pnpm add -D @cc-wf-studio/cliand run viapnpm exec ccwf
If the user has a VSCode workspace and you can't find a workflow file, search .vscode/workflows/*.json first; that's the canonical location.
Core workflow
The natural flow when the user has a workflow file in hand:
ccwf validate <file>— schema-check it. Exit 0 = clean, exit 1 = errors. Run this first whenever you receive a workflow from elsewhere.ccwf preview <file>— opens a read-only viewer (Mermaid + per-node Markdown) in the browser. Use this when the user says "show me" / "what's in this workflow?" / "見せて".ccwf export <file>orccwf run <file>— materialises the workflow as Claude Code (or another agent's) Skill files. Userunwhen the user wants the next step to be actually executing the workflow withclaude.
If a step fails, stop and surface the exact error to the user before moving on.
Subcommand reference
ccwf render <file>
Print a Markdown bundle (Mermaid flowchart + per-node execution instructions) to stdout. Use when piping to another tool or pasting into a PR / chat message.
ccwf render ./.vscode/workflows/my-workflow.json # Markdown (default)
ccwf render ./.vscode/workflows/my-workflow.json -f mermaid # ```mermaid block only
Output is the same content ccwf preview shows in the right pane.
ccwf validate <file>
Schema-check the workflow JSON.
ccwf validate ./.vscode/workflows/my-workflow.json # exit 0/1, human-readable errors on stderr
ccwf validate ./.vscode/workflows/my-workflow.json --json # prints { valid, errors[] }
Use this:
- Before
ccwf run/ccwf exportif the file is hand-edited or AI-generated - In CI / pre-commit hooks
- When the user asks "is this workflow OK?" / "壊れてない?"
ccwf preview <file>
Open a read-only viewer in the browser. Mermaid flowchart on the left, per-node Markdown on the right. Auto-reloads when the file changes on disk. Auto-shuts down 30s after the last viewer tab closes.
ccwf preview ./my-workflow.json # boot, open browser
ccwf preview ./my-workflow.json --port 51234 # pin to a port
ccwf preview ./my-workflow.json --keep-alive # don't auto-shutdown when the tab closes
Use when the user says any of: "show me", "preview", "what does this workflow do?", "open it in a browser", "見せて", "可視化して".
The printed URL has the shape http://localhost:<port>/<uuid>/. The UUID just keeps two concurrent preview sessions from clobbering each other — it isn't a security boundary, since the server only listens on the loopback interface by default.
ccwf canvas <file> (experimental)
Open the full editable canvas in the browser (same UI as the VSCode extension). Saves write back to the workflow file. Heavier than preview; reach for it only when the user explicitly wants to edit without VSCode.
ccwf canvas ./my-workflow.json
Other VSCode-only features (Slack share, Claude API upload, MCP server management, agent-specific export buttons) return a CANVAS_UNSUPPORTED error in this mode — they require the extension proper.
ccwf export <file> [--agent <name>]
Materialise the workflow as Agent Skill files for a target agent. Pure file write, no execution.
ccwf export ./my-workflow.json # --agent claude-code (default)
ccwf export ./my-workflow.json --agent cursor # cursor
ccwf export ./my-workflow.json --agent codex --cwd /tmp/proj # codex, custom output root
ccwf export ./my-workflow.json --overwrite # replace existing files
Output by --agent:
--agent |
Files emitted (relative to --cwd or process.cwd()) |
|---|---|
claude-code (default) |
.claude/agents/<sub-agent>.md (inline SubAgent nodes) + .claude/skills/<workflow>/SKILL.md |
antigravity |
.agent/skills/<workflow>/SKILL.md |
codex |
.codex/skills/<workflow>/SKILL.md |
copilot |
.github/skills/<workflow>/SKILL.md |
cursor |
.cursor/skills/<workflow>/SKILL.md + .cursor/agents/<sub-agent>.md |
gemini |
.gemini/skills/<workflow>/SKILL.md |
roo-code (Zoo Code) |
.roo/skills/<workflow>/SKILL.md |
Use export (rather than run) when the user wants the files only — e.g. checking generated content into git, inspecting before execution, or generating Skills for multiple agents in batch.
ccwf run <file> [--agent <name>] [--launch]
Same file output as ccwf export, plus a "next step" hint on stdout. --launch additionally spawns the claude binary in the output directory (best-effort, claude-code agent only).
ccwf run ./my-workflow.json --launch # write + spawn claude
ccwf run ./my-workflow.json --agent cursor # write only (cursor launch not yet wired)
Use run:
- When the user wants to execute the workflow in Claude Code right after generating it ("動かして" / "実行して" / "run this workflow")
- As the one-stop shortcut after
validatepasses
ccwf mcp --file <file>
Run the cc-wf-studio stdio MCP server in-process against <file>. Equivalent to the standalone ccwf-mcp bin. Use this to point an MCP client (Claude Code, MCP Inspector, …) at a workflow so the agent can read and edit it through MCP tools.
ccwf mcp --file ./.vscode/workflows/my-workflow.json
Typical .mcp.json snippet for Claude Code:
{
"mcpServers": {
"cc-wf-studio": {
"type": "stdio",
"command": "npx",
"args": ["@cc-wf-studio/cli", "mcp", "--file", ".vscode/workflows/my-workflow.json"]
}
}
}
The MCP server exposes 6 tools: get_workflow_schema, get_current_workflow, apply_workflow, update_nodes, list_available_agents, highlight_group_node. Use these when the user wants AI-driven editing of the workflow itself (not just rendering / running it).
ccwf install-skills / ccwf uninstall-skills
Copy this Skill bundle into a discoverable location, or remove it again.
ccwf install-skills # ~/.claude/skills/ccwf-cli/ (user-scope)
ccwf install-skills --project # ./.claude/skills/ccwf-cli/ (project-scope)
ccwf install-skills --overwrite # replace an existing copy
ccwf install-skills --dry-run # print paths without writing
ccwf uninstall-skills # remove from ~/.claude/skills/
ccwf uninstall-skills --project # remove from ./.claude/skills/
ccwf uninstall-skills --dry-run # print deletions without writing
Use cases:
- "Install the ccwf skill" / "teach Claude Code about ccwf" →
ccwf install-skills - "Update the ccwf skill" / "refresh the install" →
ccwf uninstall-skills && ccwf install-skills - "Remove the ccwf skill" / "cleanup before uninstalling the CLI" →
ccwf uninstall-skills
uninstall-skills is idempotent: running it twice prints "nothing to remove" the second time and exits 0.
Mapping user phrasing to subcommands
Use this as a lookup when the user describes intent in natural language. If the user names a file under .vscode/workflows/ or a *workflow*.json, the subcommand pattern below applies.
| User says... | Run |
|---|---|
| "Show me / preview this workflow", "見せて", "可視化して" | ccwf preview <file> |
| "Render this as Markdown", "Mermaid 図にして" | ccwf render <file> |
| "Is this workflow valid?", "壊れてない?", "schema 確認して" | ccwf validate <file> |
| "Export as a Claude Skill / agent file", "skills 化して" | ccwf export <file> (default agent) |
| "Convert for Cursor / Codex / Gemini …" | ccwf export <file> --agent <name> |
| "Run this workflow", "動かして", "実行して" | ccwf run <file> --launch |
| "Edit the canvas without VSCode", "editor を browser で開いて" | ccwf canvas <file> (mention experimental) |
| "Let an MCP client edit this workflow" | ccwf mcp --file <file> and configure .mcp.json |
| "Install the ccwf skill / teach Claude about ccwf" | ccwf install-skills [--project] |
| "Update / refresh the ccwf skill" | ccwf uninstall-skills && ccwf install-skills |
| "Remove the ccwf skill / cleanup" | ccwf uninstall-skills [--project] |
Tips & gotchas
ccwf previewURLs include a per-session UUID so two concurrent preview sessions don't collide. The server itself only binds to the loopback interface (127.0.0.1) by default, so external machines can't reach it; the UUID is a path key, not a credential.- Auto-shutdown:
previewandcanvasshut themselves down 30 seconds after the last viewer tab closes. The countdown only starts once at least one viewer has connected, so apreviewthat nobody opens stays up. Use--keep-alivefor multi-tab or LAN scenarios. ccwf run --launchrequiresclaudeon PATH. If it's missing, the command warns and exits cleanly after writing the files — that's not an error condition.ccwf canvasis experimental and missing Slack / Claude API / MCP / external-IDE export. If the user needs any of those, fall back to the VSCode extension.- Workflow file location: when the user doesn't specify a path, look first under
.vscode/workflows/*.jsonfrom the workspace root. If multiple workflows exist, list them and ask. - Validation before execution: if the workflow is hand-edited or AI-authored in the same session, run
ccwf validatebeforeccwf run/ccwf exportto catch shape errors early. .claude/commands/vs.claude/skills/: Claude Code foldedcommands/intoskills/.ccwf export --agent claude-codewrites to the new path (.claude/skills/<workflow>/SKILL.md). Existing.claude/commands/<workflow>.mdfiles are left alone — the user may want to delete them manually.
Related interfaces
ccwf is one of three entry points to the same workflow JSON; if the user already has the VSCode extension installed or wants AI-driven editing, suggest the appropriate sibling:
cc-wf-studioVSCode extension — visual canvas + Slack share + in-canvas AI editing.@cc-wf-studio/mcpstdio bin (ccwf-mcporccwf mcp) — let an external AI client read and edit workflows through MCP tools.
See the monorepo README at https://github.com/breaking-brake/cc-wf-studio for the full picture.
Files in this skill
1ccwf-cli skill questions
How do I install the ccwf-cli skill in Claude Code?
Run npx degit breaking-brake/cc-wf-studio/packages/cli/skills/ccwf-cli ~/.claude/skills/ccwf-cli. 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 ccwf-cli 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.
How can I preview a workflow in my browser?
You can use the ccwf preview <file> command to open a read-only viewer in the browser featuring a Mermaid flowchart and per-node Markdown.