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
- Classify the task as read-only, normal mutation, or destructive.
- Read current state with
list or a narrower inspect command.
- For imports, run preview or prepare first; build draft from returned skill selectors.
- For enable/disable/deploy, call
apply with full selectedLeafIds and enabledTargets.
- For updates or repairs, run
doctor before and after.
- 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.
1---2name: skill-flow3description: Use when the user asks Codex to inspect, import, enable, disable, deploy, update, repair, migrate, or uninstall Skill Flow skill groups through the skill-flow CLI or bridge protocol.4---56# Skill Flow78## Overview910Operate 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.1112## Core Rules1314- Use `skill-flow bridge --json` for structured operations and parse the JSON response.15- Never edit `~/.skillflow`, target skill directories, manifests, locks, or source checkouts directly.16- Inspect before mutating: run `list`, `inspect`, `doctor`, or `preview-import-source` first.17- Default imports to OFF by using `enabledTargets: []` unless the user explicitly asks to deploy immediately.18- Treat skill enablement and deployment as draft state: use `apply`, not direct filesystem edits.19- Explain impact before state-changing operations; require explicit confirmation for destructive operations.2021## Command Entry2223Use installed CLI:2425```bash26skill-flow bridge --json --request '{"protocolVersion":"1.0","command":"list"}'27```2829Inside this repository, use the workspace CLI:3031```bash32npm run -w skill-flow dev -- bridge --json --request '{"protocolVersion":"1.0","command":"list"}'33```3435For payload details, read `references/bridge-commands.md` before crafting a bridge request.3637## Workflow38391. Classify the task as read-only, normal mutation, or destructive.402. Read current state with `list` or a narrower inspect command.413. For imports, run preview or prepare first; build draft from returned skill selectors.424. For enable/disable/deploy, call `apply` with full `selectedLeafIds` and `enabledTargets`.435. For updates or repairs, run `doctor` before and after.446. Report `ok`, warnings, errors, changed source ids, and any blocked actions.4546## Safety Levels4748| Level | Operations | Rule |49| --- | --- | --- |50| Read-only | `list`, `doctor`, `inspect`, `inspect-enrichment`, `search-import-groups`, `scan-local-import-groups`, `preview-import-source`, `inspect-state-migration` | Execute directly when useful. |51| 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. |52| 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. |5354## Common Tasks5556| User asks | Do |57| --- | --- |58| "What groups do I have?" | Bridge `list`. |59| "Search for a skill" | Human CLI `skill-flow find <query> --json`, or bridge import search for remote groups. |60| "Import this repo, keep skills off" | `preview-import-source`, then `import-source` or `prepare-import-source` + `commit-import-source` with `enabledTargets: []`. |61| "Turn these skills on for Codex" | `inspect`, map names to leaf ids, then `apply` with `enabledTargets: ["codex"]`. |62| "Disable a skill" | `inspect`, remove its leaf id from `selectedLeafIds`, then `apply` with remaining ids. |63| "Why did deployment fail?" | `doctor`, then `inspect` for the affected source. |64| "Remove this group" | `list`/`inspect`, ask for confirmation, then `uninstall`. |6566## Common Mistakes6768- Using interactive `config` or `add` when bridge JSON can do the same job.69- Omitting `protocolVersion: "1.0"` from bridge requests.70- Passing skill names to `apply`; it requires leaf ids such as `source-id:skills/review`.71- Importing with non-empty `enabledTargets` when the user did not request deployment.72- Running `uninstall` or migration based on display names instead of exact source ids.
VintLin