Skill Flow

Overview

Operate Skill Flow through its CLI without editing state files directly. Prefer the machine-readable bridge protocol for agent work; use the human CLI only for simple commands that already emit usable output.

Core Rules

• Use skill-flow bridge --json for structured operations and parse the JSON response.
• Never edit ~/.skillflow, target skill directories, manifests, locks, or source checkouts directly.
• Inspect before mutating: run list, inspect, doctor, or preview-import-source first.
• Default imports to OFF by using enabledTargets: [] unless the user explicitly asks to deploy immediately.
• Treat skill enablement and deployment as draft state: use apply, not direct filesystem edits.
• Explain impact before state-changing operations; require explicit confirmation for destructive operations.

Command Entry

Use installed CLI:

skill-flow bridge --json --request '{"protocolVersion":"1.0","command":"list"}'

Inside this repository, use the workspace CLI:

npm run -w skill-flow dev -- bridge --json --request '{"protocolVersion":"1.0","command":"list"}'

For payload details, read references/bridge-commands.md before crafting a bridge request.

Workflow

1. Classify the task as read-only, normal mutation, or destructive.
2. Read current state with list or a narrower inspect command.
3. For imports, run preview or prepare first; build draft from returned skill selectors.
4. For enable/disable/deploy, call apply with full selectedLeafIds and enabledTargets.
5. For updates or repairs, run doctor before and after.
6. Report ok, warnings, errors, changed source ids, and any blocked actions.

Safety Levels

Level	Operations	Rule
Read-only	list, doctor, inspect, inspect-enrichment, search-import-groups, scan-local-import-groups, preview-import-source, inspect-state-migration	Execute directly when useful.
Normal mutation	bootstrap, commit-import-source, import-source, apply, update, toggle-pin, rename-source, collections, save-settings	Summarize impact; proceed if the user requested that exact change.
Destructive/high-risk	uninstall, non-dry-run migrate-state, broad repairs such as repair-state --all	Require explicit confirmation after identifying exact ids and scope.

Common Tasks

User asks	Do
"What groups do I have?"	Bridge list.
"Search for a skill"	Human CLI skill-flow find <query> --json, or bridge import search for remote groups.
"Import this repo, keep skills off"	preview-import-source, then import-source or prepare-import-source + commit-import-source with enabledTargets: [].
"Turn these skills on for Codex"	inspect, map names to leaf ids, then apply with enabledTargets: ["codex"].
"Disable a skill"	inspect, remove its leaf id from selectedLeafIds, then apply with remaining ids.
"Why did deployment fail?"	doctor, then inspect for the affected source.
"Remove this group"	list/inspect, ask for confirmation, then uninstall.

Common Mistakes

• Using interactive config or add when bridge JSON can do the same job.
• Omitting protocolVersion: "1.0" from bridge requests.
• Passing skill names to apply; it requires leaf ids such as source-id:skills/review.
• Importing with non-empty enabledTargets when the user did not request deployment.
• Running uninstall or migration based on display names instead of exact source ids.