skill-system-cli

What this skill does

# Skill System CLI

Single command `sk` that dispatches to all skill system operations. Agent-native: JSON output by default, progressive disclosure via `--help`.

This is the public user-facing contract for the skill system. Other skills are capability modules behind this entrypoint.

Inspired by [CLI-Anything](https://github.com/HKUDS/CLI-Anything) — making everything agent-native through structured CLI interfaces.

## Quick Start

```bash
# Show all domains
python3 "<this-skill-dir>/scripts/sk.py" --help

# Bootstrap a project
python3 "<this-skill-dir>/scripts/sk.py" init

# Check project status
python3 "<this-skill-dir>/scripts/sk.py" status

# Ticket operations
python3 "<this-skill-dir>/scripts/sk.py" tkt claim --ticket-id TKT-001

# Memory operations
python3 "<this-skill-dir>/scripts/sk.py" mem search "query"

# Config operations
python3 "<this-skill-dir>/scripts/sk.py" config get tkt.bundle.max_tickets

# Thin host shell MVP (installer-backed direct entry)
bash "skills/skill-system-installer/scripts/skills.sh" host-shell doctor --target .

# Audited wildcard motor nerve for commands not yet myelinated
python3 "<this-skill-dir>/scripts/sk.py" nerve shell --risk read --reason "inspect status" -- ps -ef
```

## Configuration

Runtime settings are in `config/cli.yaml`. Config is the single source of truth.

See: `../../config/cli.yaml`

## Architecture

```
sk (thin dispatcher)
├── init           → bootstrap.md Phase 1+2 logic
├── status         → aggregate project health
├── scan           → discover runnable scripts and CLI hints
├── run            → execute script with auto-detected runner
├── config         → read/write config/*.yaml
│   ├── list
│   ├── show <file>
│   ├── get <key>
│   └── set <key> <value>
├── tkt            → tkt.sh + tickets.py
│   ├── init-roadmap, create-bundle, bundle-status, close-bundle, list-bundles
│   ├── intake, list-tickets, claim, block, close
│   ├── check-open, summary, loop, startup
│   ├── refresh-new, refresh-inbox
│   ├── closure-report, scope
├── mem            → mem.py
│   ├── search, store, status, tags, categories
├── gate           → skill-system-gate
│   └── validate
├── nerve          → audited wildcard motor gateway
│   └── shell
└── install        → skills.sh
    ├── list, add, status, update, sync
```

## Design Principles

1. **Thin dispatcher** — `sk.py` never reimplements logic. It routes to existing scripts via subprocess or import.
2. **JSON-first** — All output follows the last-line JSON contract. Agents parse the last line.
3. **Progressive disclosure** — No args shows domains. `sk tkt` shows tkt actions. `sk tkt claim --help` shows claim options.
4. **Config-aware** — Reads from `config/` for defaults.
5. **Idempotent init** — `sk init` only creates what's missing, never overwrites.
6. **Note governance** — `sk status` exposes AGENTS.md guidance merged with `note/preferences.md`, `note/constraints.md`, and `note/style.md`, with note files taking precedence.

## Output Contract

Every command emits JSON on the last line:

```json
{"status": "ok", ...}
{"status": "error", "message": "...", ...}
```

## Domains

### `sk init`
Bootstrap project structure. Scaffolds config/, note/, .tkt/, checks PostgreSQL.

It also scaffolds note governance overlays when missing:
- `note/preferences.md`
- `note/constraints.md`
- `note/style.md`

### `sk status`
Aggregate project health: config, note, tkt, postgres, skills counts, plus merged governance context.

### `sk config`
Read/write config values using dot-path notation: `sk config get tkt.bundle.max_tickets`.

### `sk tkt`
Full ticket lifecycle — both filesystem bundles (tkt.sh) and DB durable tickets (tickets.py).

### `sk mem`
Memory operations — search, store, list, compact, export, status, tags, categories.

Examples:

```bash
python3 "<this-skill-dir>/scripts/sk.py" mem search "fraud" --scope project --limit 5
python3 "<this-skill-dir>/scripts/sk.py" mem store --type semantic --category fraud --title note --content hello --scope session
python3 "<this-skill-dir>/scripts/sk.py" mem list --scope project --limit 20
python3 "<this-skill-dir>/scripts/sk.py" mem compact --scope project
python3 "<this-skill-dir>/scripts/sk.py" mem export --format json --scope global
```

### `sk nerve shell`

Audited wildcard shell nerve for commands that are not yet formal SK nerves.
This is observe/enforce at the wrapper boundary only; it does not install a
global hook and does not constrain existing Codex limbs.

```bash
python3 "<this-skill-dir>/scripts/sk.py" nerve shell \
  --risk read \
  --reason "inspect current process state" \
  -- ps -ef
```

Rules:

- `read` commands run if the command shape is not obviously write/danger.
- `write` and `danger` require `--break-glass <artifact>` or `--behavior <artifact>`.
- Every attempt writes an audit JSON under `.tkt/nerve-shell/`.
- Repeated wildcard command shapes are myelination debt; convert them into a
  formal SK command once the pattern stabilizes.

### `sk physiology`
Anatomy routing is being projected into the public CLI surface.

Target public shape:

```bash
python3 "<this-skill-dir>/scripts/sk.py" physiology anatomy doctor --project-root /datas/store162/arthur0824hao/Work --json
```

Until routing lands in `sk.py`, use the documented fallback:

```bash
python3 "skills/skill-system-physiology/scripts/physiology.py" anatomy doctor --project-root /datas/store162/arthur0824hao/Work --json
```

### `sk install`
Skill management — list, add, update, sync.

```skill-manifest
{
  "schema_version": "2.0",
  "id": "skill-system-cli",
  "version": "1.2.0",
  "capabilities": [
    "cli-dispatch", "project-init", "project-status",
    "cli-scan", "cli-run", "gate-dispatch",
    "config-read", "config-write",
    "tkt-dispatch", "tkt-create-shortcut", "mem-dispatch", "install-dispatch", "router-dispatch", "graph-dispatch", "coder-lifecycle-dispatch", "coder-harness-dispatch", "debug-lifecycle-dispatch", "reviewer-comms-dispatch", "cron-dispatch", "ans-dispatch", "github-dispatch", "creator-dispatch"
  ],
  "effects": ["fs.read", "fs.write", "db.read", "db.write", "proc.exec"],
  "operations": {
    "init": {
      "description": "Bootstrap project structure and report what was created or verified.",
      "input": {
        "check": {"type": "boolean", "required": false, "description": "Detect only, do not create missing structure"}
      },
      "output": {
        "description": "Bootstrap report",
        "fields": {"status": "string", "init_report": "object"}
      },
      "entrypoints": {
        "unix": ["python3", "{skill_dir}/scripts/sk.py", "init"],
        "windows": ["python", "{skill_dir}/scripts/sk.py", "init"]
      }
    },
    "status": {
      "description": "Show global project health across config, note, TKT, postgres, and skills inventory.",
      "input": {},
      "output": {
        "description": "Aggregated health report",
        "fields": {"status": "string", "config": "object", "note": "object", "tkt": "object", "postgres": "object", "skills": "object"}
      },
      "entrypoints": {
        "unix": ["python3", "{skill_dir}/scripts/sk.py", "status"],
        "windows": ["python", "{skill_dir}/scripts/sk.py", "status"]
      }
    },
    "scan": {
      "description": "Scan repository scripts and infer runnable CLI targets.",
      "input": {},
      "output": {
        "description": "Discovered script targets",
        "fields": {"status": "string", "targets": "array"}
      },
      "entrypoints": {
        "unix": ["python3", "{skill_dir}/scripts/sk.py", "scan"],
        "windows": ["python", "{skill_dir}/scripts/sk.py", "scan"]
      }
    },
    "run": {
      "description": "Run any discovered script with auto-detected runner.",
      "input": {
        "script": {"type": "string", "required": true, "description": "Script path or basename"},
        "args": {"type": "array", "required": false, "description": "Pass-through arguments"}
      },
      "output": {
        "description":