--- name: skill-flow description: 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. ---

# 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:

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

Inside this repository, use the workspace CLI:

```bash 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.