Development
Plugin
skill-flow
Turn scattered AI agent skills into organized workflows. Install, manage, and share skills across every major coding agent — Claude Code, Cursor, Grok Build, Copilot, Kimi Code, WorkBuddy, CodeBuddy, ZCode, and more.
Plugin Signal63/100Solid
maintained89
capable14
documented100
adopted51
Install
$ npx -y skills add VintLin/skill-flow --agent claude-code
Run the curl in your terminal, the rest in Claude Code.
Stats
251
Stars
15
Forks
Active
Maintenance
Swift
Language
Apache-2.0
License
21d ago
Last commit
4mo ago
Created
Repo: VintLin/skill-flow
What's inside
README
1Skill Flow
Turn scattered AI agent skills into organized workflows.
Install, manage, and share skills across every major coding agent — Claude Code, Cursor, Grok Build, Copilot, Kimi Code, WorkBuddy, CodeBuddy, ZCode, and more.
Search and import skills from skills.sh, GitHub, or local sources. Deploy to multiple agents at once. Keep everything organized and up to date.
Why This Exists
Installing skills one by one breaks down at scale:
- Repos contain multiple related skills, but you install them separately
- Different agents expect different locations
- Updates drift silently
- Unmanaged folders accumulate
- Nobody tracks what's actually deployed
skill-flow preserves the workflow group. One source remains one cohesive unit—inspect it, select skills, deploy to multiple targets, update cleanly, and always know your state.
What You Get
- Grouped source management: local, Git, and skills.sh sources all flow through the same import model.
- Multi-agent deployment: deploy one selected skill set to Claude Code, Codex, Cursor, Grok Build, Gemini CLI, OpenCode, OpenClaw, Hermes Agent, MiniMax Code, Kimi Code, WorkBuddy, CodeBuddy, Trae, Trae CN, Windsurf, ZCode, and more.
- Interactive config flow: Ink-based TUI for add/config flows, selection state, review, and repair.
- Desktop app on macOS 15+: SwiftUI main window, import view, detail panel, settings, and menu bar quick config.
- Explicit state:
manifest.jsonstores intent,lock.jsonstores resolved inventory and deployments. - Bridge protocol: machine-readable desktop/helper entrypoint via
skill-flow bridge --json. - Repair and diagnosis:
doctor,repair-source,repair-state, andrepair-targetscover the parts that usually rot first.
Interface Preview
| Menu Bar | Import |
|---|---|
 |  |
| Detail | Settings |
|---|---|
 |  |
Quick Start
Install
npm install -g skill-flow
skill-flow --help
Or run without a global install:
npx skill-flow --help
Desktop prerequisites
Skill Flow Desktop release builds include a bundled native Node.js/npm/npx toolchain for the desktop helper and skills.sh imports, so double-click launch does not depend on shell-managed Node paths from tools like asdf or nvm.
gitis required for non-GitHub Git sources
Development builds and damaged release bundles can still fall back to system Node.js 20 or newer with npm/npx. If the desktop app detects a missing dependency, it will surface an actionable error and point back to this section.
Typical flow
# Add a source
skill-flow add garrytan/gstack
# Review installed workflow groups
skill-flow list
# Migrate or mirror a known source set
skill-flow import-manifest skill-group-install-manifest.json --dry-run
skill-flow import-manifest skill-group-install-manifest.json --apply --skip-existing
skill-flow only garrytan-gstack --targets codex,cline --all-skills
skill-flow list --ids --warnings
# Open the interactive config UI
skill-flow config
# Search installed skills, built-in catalogs, and skills.sh
skill-flow find browser
# Update one source or all sources
skill-flow update garrytan-gstack
skill-flow update --all
# Diagnose drift or broken projections
skill-flow doctor
Machine bridge
The desktop app and helper tooling talk to the CLI through a versioned JSON protocol:
printf '%s' '{"protocolVersion":"1.0","command":"list"}' | skill-flow bridge --json
Supported Sources
skill-flow add <source> supports:
- local folders
owner/repoGitHub shorthand- full HTTPS Git URLs
- SSH Git URLs
- GitHub tree URLs
clawhub:<slug>[@version]
Examples:
skill-flow add ~/code/my-skills
skill-flow add garrytan/gstack
skill-flow add https://github.com/garrytan/gstack.git
skill-flow add git@github.com:garrytan/gstack.git
skill-flow add https://github.com/garrytan/gstack/tree/main/skills
skill-flow add clawhub:example/skill-pack
skill-flow add clawhub:example/skill-pack@1.2.3
Use --path <repoSubpath> when the repo is large but your default selection should start from one subtree.
Supported Targets
Current built-in targets:
- Claude Code
- Codex
- Cursor
- Grok Build
- GitHub Copilot
- Gemini CLI
- OpenCode
- OpenClaw
- Hermes Agent
- MiniMax Code
- Kimi Code
- WorkBuddy
- CodeBuddy
- Pi
- Trae
- Trae CN
- Windsurf
- Roo Code
- Cline
- Amp
- Kiro
- ZCode
Target paths can be overridden with SKILL_FLOW_TARGET_* environment variables.
Command Map
| Command | What it does |
|---|---|
add <source> | Import a source and choose skills/targets |
list | Show workflow groups and current health |
list --ids --warnings | Show source IDs and warning details for migration/debugging |
enable <sourceIds...> --targets <ids> --all-skills | Enable registered groups for targets; --all-skills fills empty selections first |
disable <sourceIds...> | Turn registered groups OFF without uninstalling |
only <sourceIds...> --targets <ids> --all-skills | Keep only selected groups ON; --all-skills fills empty selections first |
import-manifest <file> | Batch import source manifests; JSON entries with targets require skills: "all" |
find <query> / search <query> | Search installed skills, built-in Git catalogs, and skills.sh |
config | Open the interactive configuration UI |
update [sourceId] --all | Refresh one source or all registered sources |
doctor | Diagnose drift, missing paths, and projection problems |
migrate-state --to v2 [--dry-run] | Inspect or migrate the local state root to schema v2 |
repair-source [sourceId] --all | Rebuild source checkout metadata |
repair-state [sourceId] --all | Rebuild source-side state |
repair-targets [sourceId] --all | Repair projected target contents |
uninstall <sourceIds...> | Remove groups and their deployments |
bridge --json | Execute machine protocol requests |
How State Works
skill-flow keeps one state root, defaulting to ~/.skillflow/.
manifest.json: what you wantlock.json: what is actually installedsource/local/*: imported local or adopted unmanaged sourcessource/git/*: Git source cachesource/clawhub/*: skills.sh source cachecatalog/git/*: built-in Git catalog cache
Target directories are deployment outputs, not the source of truth.
State schema migration
Use a dry run before applying a schema migration:
skill-flow migrate-state --to v2 --dry-run
skill-flow migrate-state --to v2
SKILL_FLOW_STATE_ROOT=/custom/path skill-flow migrate-state --to v2
The default state root is ~/.skillflow/. A normal migration creates a backup named <stateRoot>.backup-YYYYMMDD-HHMMSS, rewrites the authority files, and prunes rebuildable cache under catalog/; cache is rebuilt by later CLI or desktop reads. Target directories are not authoritative and should not be used to reconstruct state. If target folders look stale after migration, run skill-flow repair-targets --all.
To roll back, stop Skill Flow, move the backup state root back into place, then run skill-flow migrate-state --to v2 --dry-run or use the desktop migration status check before applying migration again.
FAQ
Where does skill-flow store data?
By default, state lives under ~/.skillflow/. manifest.json records the workflow you want, lock.json records the resolved inventory and deployments, and the source/* directories cache imported sources.
Does deployment overwrite files in target agent folders?
skill-flow treats target directories as deployment outputs. The selected skills for a workflow group are projected there from state, so you should treat those files as generated results rather than edit them as the source of truth.
When should I use doctor vs repair-*?
Start with skill-flow doctor when something looks wrong and you want a diagnosis first. Use repair-source when source checkout metadata is broken, repair-state when source-side state needs rebuilding, and repair-targets when deployed target contents have drifted from the current state.
Monorepo Layout
.
├── apps
│ ├── cli/ # published npm package and CLI entrypoint
│ └── desktop-mac/ # SwiftUI desktop app for macOS 15+
├── packages
│ ├── core-engine/ # inventory, deployment, doctor, bootstrap services
│ ├── domain/ # domain models and core types
│ ├── integration/ # Git, GitHub, skills.sh, path, naming integrations
│ ├── query/ # shared runtime and bridge-facing orchestration
│ ├── shared-types/ # bridge protocol types
│ ├── storage/ # manifest, lock, preferences, cache persistence
│ └── tui/ # Ink add/find/config UI
├── docs/ # architecture, contributor docs, references, plans
└── releases/ # release notes
Development
npm install
npm run build
npm test
CLI dev loop:
npm run -w skill-flow dev -- --help
Desktop dev loop:
npm run build
cd apps/desktop-mac
swift build
swift test
Debugging the desktop shell against a local CLI build:
export SKILL_FLOW_DESKTOP_HELPER_OVERRIDE=/absolute/path/to/apps/cli/dist/cli.js
Unsigned desktop packaging:
scripts/release/package-desktop-mac.sh --arch arm64
scripts/release/package-desktop-mac.sh --arch x86_64
scripts/release/package-desktop-mac.sh --arch universal
Open-source macOS release flow:
scripts/release/release-github.sh all
Unsigned macOS install notes:
- Apple Silicon Macs can use
Skill-Flow-arm64.dmgorSkill-Flow-universal.dmg. - Intel Macs can use
Skill-Flow-x86_64.dmgorSkill-Flow-universal.dmg. - Copy
Skill Flow.apptoApplications, then open it once with Finder'sOpenaction if Gatekeeper blocks it. - If macOS still marks the app as quarantined, run:
xattr -dr com.apple.quarantine "/Applications/Skill Flow.app"
Star History
License
Apache License 2.0. See LICENSE.
File tree
545VintLin/skill-flowView on GitHub
.gitignore
.npmignore
apps/
cli/
package.json
src/
bridge-command.ts
bridge-runner.ts
cli.tsx
desktop-bridge.ts
import-manifest-command.ts
state-migration-command.ts
tests/
add-flow-ui.test.ts
add-prepare-flow.test.ts
add-selection-and-find-command.test.ts
bridge-command.test.ts
cli-utils.test.ts
config-integration.test.ts
config-ui-utils.test.ts
import-manifest-command.test.ts
inventory-service-precedence.test.ts
npm-package.test.ts
release-metadata.test.ts
skill-flow.test.ts
source-parsing-compatibility.test.ts
state-migration-cli.test.ts
target-definitions.test.ts
test-helpers.ts
tsconfig.json
vitest.config.ts
desktop-mac/
Package.resolved
Package.swift
README.md
Sources/
DesktopApp/
App/
ActionIcon.swift
DesktopAppContainer.swift
DesktopLanguage.swift
DesktopResourceLocator.swift
L10n.swift
MenuBarIcon.swift
SkillFlowDesktopApp.swift
Components/
AgentIcon.swift
DesktopInteractionMotion.swift
DetailInfoIconLibrary.swift
GroupCardComponents.swift
GroupMetadataIconLibrary.swift
GroupTagComponents.swift
MarkdownDocumentRenderer.swift
MarkdownDocumentView.swift
MenuBar/
MenuBarQuickConfigView.swift
MenuBarScreenState.swift
WrappingHStack.swift
Navigation/
.gitkeep
DesktopNavigator.swift
DesktopRoute.swift
Resources/
ActionIcons/
back.svg
close.svg
delete.svg
drag-handle.svg
externalLink.svg
import-local-scan.svg
import-local.svg
import-recommended.svg
import.svg
more.svg
pin.svg
plus.svg
project-warning.svg
project.svg
search-submit-enter.svg
search.svg
settings.svg
skill-group-editor.svg
star.svg
tag-add.svg
tag-delete.svg
update.svg
AgentIcons/
amp.svg
claude-code.svg
clawdbot.svg
cline.svg
codebuddy.svg
codex.svg
copilot.svg
cursor.svg
gemini.svg
grok-build.svg
hermesagent.svg
kimi.svg
kiro-cli.svg
minimax.svg
opencode.svg
roo.svg
trae.svg
windsurf.svg
zcode.svg
AppIcon.icns
DetailIcons/
detail-info-version.svg
detail-info-word-count.svg
en.lproj/
Localizable.strings
GroupCardIcons/
group-metadata-download.svg
group-metadata-github.svg
group-metadata-local-file.svg
group-metadata-skills.svg
group-metadata-star.svg
ImportRecommendations/
recommendations.json
ja.lproj/
Localizable.strings
MenuBar/
menu_icon.svg
zh-Hans.lproj/
Localizable.strings
Runtime/
.gitkeep
Bridge/
BridgeClient.swift
DesktopBridgeCommandFacade.swift
DesktopBridgeQueryFacade.swift
MutationCoordinator.swift
DesktopCacheMaintenance.swift
DesktopCommanding.swift
DesktopGroupTagStore.swift
DesktopMutationCoordinator.swift
DesktopQuerying.swift
DesktopRuntime.swift
DesktopRuntimeDependencies.swift
DesktopSettingsStore.swift
DesktopUpdateChecker.swift
DesktopUpdateInstaller.swift
DesktopWorkspaceMemoryStore.swift
GroupOperationCoordinator.swift
GroupOperationQueue.swift
Models/
BridgeDiagnostic.swift
BridgePayloadDecoder.swift
BridgeProtocol.swift
DesktopIssuePresentation.swift
Screens/
Detail/
.gitkeep
DetailDocumentStore.swift
DetailScreen.swift
DetailScreenContainer.swift
Home/
.gitkeep
HomeScreen.swift
HomeScreenContainer.swift
MainView.swift
Import/
.gitkeep
ImportScreen.swift
ImportScreenContainer.swift
ImportSkillSelectionResolver.swift
Settings/
.gitkeep
SettingsScreen.swift
SettingsView.swift
Store/
AgentDisplayPreference.swift
AsyncResourceState.swift
DesktopAppState.swift
GroupTagMigration.swift
GroupTagState.swift
ImportState.swift
ProjectionRules.swift
SelectionState.swift
SettingsState.swift
ViewState.swift
WorkspaceState.swift
ViewModels/
AppStateManager.swift
CollectionLogic.swift
DetailLogic.swift
DetailViewModel.swift
GroupTagController.swift
HomeViewModel.swift
ImportLogic.swift
ImportRecommendations.swift
ImportRepositoryIdentity.swift
ImportViewModel.swift
MainViewModel.swift
SettingsViewModel.swift
SourceManagement.swift
TaskCoordinator.swift
UIModels.swift
Tests/
SkillFlowDesktopTests/
AgentIconTests.swift
BridgeClientExecutionTests.swift
BridgePayloadDecoderTests.swift
BridgeProtocolCatalogTests.swift
ClickTargetRegressionTests.swift
DesktopAppContainerTests.swift
DesktopInteractionMotionTests.swift
DesktopInteractionRegressionTests.swift
DesktopIssuePresentationCatalogTests.swift
DesktopLocalizationTests.swift
DesktopMutationCoordinatorTests.swift
DesktopNavigationTests.swift
DesktopResourceLocatorTests.swift
DesktopRuntimeFacadeTests.swift
DesktopRuntimeTests.swift
DesktopUpdateCheckerTests.swift
DesktopUpdateInstallerTests.swift
DesktopWorkspaceMemoryStoreTests.swift
DetailDocumentStoreTests.swift
DetailLoadingLayoutTests.swift
DetailLogicInputTests.swift
DetailScreenContainerTests.swift
DetailViewModelTests.swift
GroupCardScaleTests.swift
GroupOperationQueueTests.swift
GroupTagControllerTests.swift
HomeScreenContainerSortingTests.swift
HomeViewModelTests.swift
ImportScreenContainerTests.swift
ImportToastDiagnosticsFormatterTests.swift
ImportViewModelTests.swift
MainViewModelCollectionTests.swift
MainViewModelProjectScopeTests.swift
MainViewModelRouteTests.swift
MainViewModelSelectionTests.swift
MarkdownDocumentRendererTests.swift
MenuBarIconTests.swift
MutationCoordinatorTests.swift
ProjectionRulesTests.swift
SettingsStateTests.swift
SettingsViewModelTests.swift
SettingsViewTests.swift
WorkflowCoverageTests.swift
CHANGELOG.md
CONTEXT.md
docs/
adr/
0001-shared-desktop-suite-for-workspace-memory.md
0002-desktop-group-operation-queue.md
ARCHITECTURE.md
archives/
plans/
00-data-model.md
01-overview-and-data-model.md
01-state-contract.md
02-migration-tool.md
02-state-contract-and-migration.md
03-import-desktop-verification.md
03-import-selector-contract.md
04-architect-review-and-closure-checklist.md
04-desktop-bridge.md
05-v1-authority-public-export-cleanup.md
05-verification-and-release.md
06-data-structure-inventory-and-terminology.md
07-serial-documentation-workflow.md
08-stage-0-terminology-closure.md
2026-05-28-home-sidebar-background-plan.md
2026-05-29-home-sidebar-full-collapse-plan.md
2026-05-29-home-sidebar-integrated-header-plan.md
2026-05-30-titlebar-traffic-light-alignment.md
2026-06-04-import-data-contract-redesign.md
2026-06-04-import-timeout-and-feedback.md
2026-06-04-state-schema-v2-finalization-completed/
00-current-execution-plan.md
2026-06-06-v2-compat-debt-cleanup-superseded/
00-current-execution-plan.md
01-data-structure-optimization-recommendations.md
02-authority-structure-audit.md
03-decision-confirmations.md
2026-06-07-v2-authority-cleanup-completed/
01-remaining-task-summary.md
03-skill-file-path-decision.md
04-architect-review-and-closure-checklist.md
04-final-change-list.md
04-source-revision-decision.md
05-multi-agent-audit-result.md
06-error-code-naming-decision.md
06-fix-verification-and-closure-review.md
07-test-coverage-matrix.md
2026-07-01-bridge-command-catalog.md
legacy-plan/
cache/
assets/
ASSET_2026-04-01_missing-information-checklist.md
ASSET_2026-04-01_official-path-and-prereq-sources.md
ASSET_2026-04-01_reference-project-findings.md
ASSET_2026-04-02_skill-flow-current-vs-target-path-matrix.md
ASSET_2026-04-02_windows-linux-expanded-path-matrix.md
bug/
BUG_codex-gstack-mounted-but-ui-reverts.md
cross-platform-desktop/
cross-platform-desktop-1/
CURRENT_IMPLEMENTATION_PLAN.md
DESKTOP_CONTRACT.md
README.md
UI_PARITY_GAP.md
DESKTOP_IMPLEMENTATION.md
FULL_CROSS_PLATFORM_DESIGN.md
FULL_CROSS_PLATFORM_IMPLEMENTATION_PLAN.md
TARGET_PATHS.md
UI_PARITY_IMPLEMENTATION_PLAN.md
PLAN_v1.0.0_mount-projection-unification.md
PLAN_v1.0.1_agent-settings-ordering.md
PLAN_v1.0.2_project-scoped-group-card-config.md
PLAN_v1.0.3_desktop-interaction-motion.md
PLAN_v1.0.4_group-detail-performance-architecture.md
PLAN_v1.3.1_desktop_cross_platform_parity.md
PLAN_v1.3.2_custom_agent_targets.md
superpowers/
plans/
2026-03-31-project-scope-preferences.md
2026-04-01-cross-platform-desktop-research.md
2026-04-01-cross-platform-desktop.md
PLAN_v1.3.6.md
state-schema-v2-control-plan.md
README.md
specs/
2026-05-28-home-sidebar-background-design.md
2026-05-29-home-sidebar-full-collapse-design.md
2026-05-29-home-sidebar-integrated-header-design.md
2026-05-30-titlebar-traffic-light-alignment-design.md
2026-06-02-skill-group-editor-design.md
2026-06-03-import-timeout-and-feedback-design.md
COMMIT_AND_PACKAGE.md
contracts/
README.md
DESIGN.md
FEATURE_INDEX.md
feedback/
FEEDBACK_animation_candidate_audit_2026-03-31.md
FEEDBACK_click_target_audit_2026-03-31.md
FEEDBACK_skill-flow-user-feedback-2026-06-26-detailed.md
FEEDBACK_skill-flow-user-feedback-2026-06-26-summary.md
README.md
issues/
ISSUE_8_plugin_assets_and_target_routing_user_report.md
ISSUE_8_plugin_assets_and_target_routing.md
README.md
PRODUCT.md
README.md
references/
README.md
REF_clash-verge-rev_cross-platform_strategy.md
REF_group-card-element-visibility-matrix.md
REF_group-card-usage-context.md
REF_vibe-usage-project-tracking.md
RELEASE_PROCESS.md
superpowers/
plans/
2026-05-31-mac-package-size-optimization.md
2026-05-31-rosetta-native-desktop-runtime.md
2026-05-31-skill-group-rename-original-name.md
2026-06-02-skill-group-editor.md
2026-06-03-skill-group-editor-ui-polish.md
2026-06-04-import-preparation-cache.md
2026-06-04-import-timeout-and-feedback.md
2026-06-07-v2-authority-cleanup-remaining/
00-current-execution-plan.md
07-third-round-audit.md
2026-06-08-group-tag-persistence.md
2026-06-08-group-update-selection-and-indicator.md
2026-06-10-home-group-card-tag-order.md
2026-06-19-desktop-issue-presentation-catalog.md
2026-06-24-desktop-dmg-update-flow.md
2026-06-24-local-scan-import-source-path-policy.md
2026-06-26-cli-migration-usability.md
2026-06-28-cli-selection-target-semantics.md
2026-07-17-architecture-deepening.md
README.md
specs/
2026-05-27-skill-management-design.md
2026-05-31-skill-group-rename-original-name-design.md
2026-06-03-import-timeout-and-feedback-design.md
2026-06-03-skill-group-editor-ui-polish-design.md
2026-06-07-import-page-unified-grid-design.md
2026-06-08-group-tag-persistence-design.md
2026-06-08-group-update-selection-and-indicator-design.md
2026-06-10-home-group-card-tag-order-design.md
2026-06-19-desktop-issue-presentation-catalog-design.md
2026-06-24-local-scan-import-source-path-policy-design.md
2026-06-26-cli-migration-usability-design.md
2026-06-27-cli-selection-target-semantics-design.md
verification/
GROUP_CARD_STATE_MATRIX.md
mount-lifecycle-matrix.md
README.md
img/
img-1.jpg
img-2.png
... 236 moreFAQ
skill-flow is a Claude Code plugin with 1 hand-picked skill for development work, indexed on Flowy. Install it with the command on its page. It includes skill-flow. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.
- What is skill-flow?
- Turn scattered AI agent skills into organized workflows. Install, manage, and share skills across every major coding agent — Claude Code, Cursor, Grok Build, Copilot, Kimi Code, WorkBuddy, CodeBuddy, ZCode, and more.
- How do I install skill-flow?
- Run these in Claude Code: npx -y skills add VintLin/skill-flow --agent claude-code. Then prompt normally.
- Does skill-flow auto-invoke its skills?
- Not yet. It is indexed on Flowy as a plain plugin. Request auto-invocation on its page and Flowy will route its skills for you as you prompt.
- Is skill-flow free?
- Yes. Flowy is free and open source, with nothing gated. You can read every skill in full before you install.