Skillflow

简体中文

Skillflow is a local-first workflow builder for composing Claude, Codex, Cursor, and manual skills into reusable workflow skills.

It scans skills and commands that already exist on your machine, lets you arrange them in a visual workflow designer, validates the graph, and generates target-tool SKILL.md packages with a canonical workflow.json next to them.

Why Skillflow

• Local-first by default: project state lives under .skillflow/; global state lives under ~/.skillflow/.
• Multi-tool skill registry: import Claude, Codex, Cursor, and manual SKILL.md resources from known global and project directories.
• Workflow generation: compose imported resources into ordered nodes and generate runnable skills for supported target tools.
• Explicit handoff rules: same-tool edges can be automatic, confirm-before-continue, or manual; cross-tool edges are forced to manual handoff.
• Recoverable runtime state: generated workflows include bounded recovery guidance for active runs, pending tasks, handoffs, and artifact summaries.

Install

npm install -g @lininn/skillflow

Verify the installation:

skillflow --version
skillflow --help

Skillflow requires Node.js 18 or newer.

Quick Start

Start the UI for the current project:

skillflow ui

Or point Skillflow at another project directory:

skillflow ui --project /absolute/path/to/project

Skillflow starts a local web server and prints a URL such as:

Skillflow UI: http://127.0.0.1:12345

Open that URL to scan skills, build workflows, validate them, and generate target-tool skills.

Workflow

1. Scan or import resources

Use the UI to scan known directories or import a manual path. Skillflow discovers:

• ~/.claude/skills/
• ~/.codex/skills/
• ~/.cursor/skills/
• <project>/.claude/skills/
• <project>/.codex/skills/
• <project>/.cursor/skills/
• Claude command markdown files
• manual directories that contain SKILL.md

Project-scoped imports are stored in:

<project>/.skillflow/skills/index.json

Global imports are stored in:

~/.skillflow/skills/index.json

2. Build a workflow

Create workflow nodes from imported skills, commands, or subcommands. Each workflow is stored as:

<project>/.skillflow/workflows/<workflow-name>/workflow.json

3. Configure nodes and edges

Nodes define the resource to execute and any node-specific prompt constraints.

Edges define how context moves between nodes:

| Mode | Behavior | | --- | --- | | auto | Continue automatically when there is one unambiguous next step. | | ask | Ask the user before moving to the downstream node. | | manual | Stop and require a manual handoff before continuing. |

Cross-tool transitions are always manual because Skillflow does not programmatically invoke another host tool on your behalf.

4. Validate and generate

Validation checks graph shape, node references, edge compatibility, and scope rules.

Generation writes a target-tool skill directory, for example:

<project>/.claude/skills/<workflow-name>/SKILL.md
<project>/.claude/skills/<workflow-name>/workflow.json

The generated skill can then be invoked from the target tool's normal skill or command surface.

Runtime Contract

Generated SKILL.md files treat workflow.json as the canonical workflow source. The generated instructions enforce these boundaries:

1. The workflow file has priority over prose.
2. Each node executes only the referenced skill or command.
3. Edge modes control whether execution continues automatically, asks first, or stops.
4. Cross-tool boundaries require manual handoff.
5. Recovery loads only the active run, selected pending task, direct handoff payload, and bounded artifact summaries needed for the next step.

Skillflow is a workflow builder and generator. It does not include a skillflow run engine in this version.

Local Data Layout

Project state:

<project>/.skillflow/
├── skills/
│   └── index.json
├── capabilities/
│   └── index.json
├── runs/
│   ├── index.json
│   └── <runId>/
│       ├── state.json
│       ├── events.jsonl
│       ├── handoffs/
│       └── artifacts/
└── workflows/
    └── <name>/
        └── workflow.json

Global state:

~/.skillflow/
├── skills/
│   └── index.json
└── capabilities/
    └── index.json

Development

npm install
npm run build
npm test

The test suite covers CLI wiring, server routes, static assets, skill discovery, workflow validation, workflow generation, capability storage, and recovery behavior.

Project Structure

skillflow/
├── bin/skillflow.js
├── src/
│   ├── cli/
│   ├── core/
│   ├── server/
│   └── web/
├── templates/
├── test/
└── docs/

Publishing

The package is published as:

npm install -g @lininn/skillflow

Repository:

https://github.com/lininn/skillflow

License

MIT