Back to Details

skill-system-cli

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill System CLI

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 — making everything agent-native through structured CLI interfaces.
单个命令
sk
可调度所有技能系统的全部操作。原生适配Agent：默认输出JSON格式，通过
--help
参数逐步展示更多详细信息。
这是技能系统面向用户的公开契约，其他技能均作为该入口背后的能力模块。
灵感来源于CLI-Anything——通过结构化CLI接口让所有功能原生支持Agent。

Quick Start

快速开始

bash
undefined
bash
undefined

Show all domains

Show all domains

python3 "<this-skill-dir>/scripts/sk.py" --help
python3 "<this-skill-dir>/scripts/sk.py" --help

Bootstrap a project

Bootstrap a project

python3 "<this-skill-dir>/scripts/sk.py" init
python3 "<this-skill-dir>/scripts/sk.py" init

Check project status

Check project status

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

Ticket operations

Ticket operations

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

Memory operations

Memory operations

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

Config operations

Config operations

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

Thin host shell MVP (installer-backed direct entry)

Thin host shell MVP (installer-backed direct entry)

bash "skills/skill-system-installer/scripts/skills.sh" host-shell doctor --target .
undefined
bash "skills/skill-system-installer/scripts/skills.sh" host-shell doctor --target .
undefined

Configuration

配置

Runtime settings are in 
config/cli.yaml
. Config is the single source of truth.
See: 
../../config/cli.yaml
运行时设置存储在
config/cli.yaml
中，配置是唯一的事实来源。
查看：
../../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
└── install        → skills.sh
    ├── list, add, status, update, sync
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
└── 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.
  1. 轻量调度器 — 
    sk.py
    从不重复实现逻辑，而是通过子进程或导入的方式路由到现有脚本。
  2. 优先JSON格式 — 所有输出遵循“最后一行是JSON”的契约，Agent解析最后一行内容。
  3. 逐步披露信息 — 不带参数时显示所有领域；
    sk tkt
    显示tkt相关操作；
    sk tkt claim --help
    显示claim命令的选项。
  4. 感知配置 — 从
    config/
    目录读取默认配置。
  5. 幂等初始化 — 
    sk init
    仅创建缺失的内容，从不覆盖现有内容。
  6. 说明文档治理 — 
    sk status
    会展示AGENTS.md中的指导内容，并与
    note/preferences.md
    、
    note/constraints.md
    和
    note/style.md
    合并，其中说明文档文件的优先级更高。

Output Contract

输出契约

Every command emits JSON on the last line:
json
{"status": "ok", ...}
{"status": "error", "message": "...", ...}
每个命令的最后一行都会输出JSON：
json
{"status": "ok", ...}
{"status": "error", "message": "...", ...}

Domains

领域

sk init

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
初始化项目结构。创建config/、note/、.tkt/目录，并检查PostgreSQL状态。
当相关文件缺失时，它还会自动创建说明文档治理覆盖文件：
  • note/preferences.md
  • note/constraints.md
  • note/style.md

sk status

sk status

Aggregate project health: config, note, tkt, postgres, skills counts, plus merged governance context.
汇总项目健康状态：包括配置、说明文档、TKT、postgres、技能数量，以及合并后的治理上下文。

sk config

sk config

Read/write config values using dot-path notation: 
sk config get tkt.bundle.max_tickets
.
使用点路径符号读写配置值：
sk config get tkt.bundle.max_tickets
。

sk tkt

sk tkt

Full ticket lifecycle — both filesystem bundles (tkt.sh) and DB durable tickets (tickets.py).
完整的工单生命周期管理——同时支持文件系统 bundle（tkt.sh）和数据库持久化工单（tickets.py）。

sk mem

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
内存操作——搜索、存储、列出、压缩、导出、状态查看、标签管理、分类管理。
示例：
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 install

sk install

Skill management — list, add, update, sync.
skill
{
  "schema_version": "2.0",
  "id": "skill-system-cli",
  "version": "1.0.0",
  "capabilities": [
    "cli-dispatch", "project-init", "project-status",
    "cli-scan", "cli-run", "gate-dispatch",
    "config-read", "config-write",
    "tkt-dispatch", "mem-dispatch", "install-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": "Script stdout/stderr passthrough",
        "fields": {"status": "string"}
      },
      "entrypoints": {
        "agent": "Invoke scripts/sk.py run <script> [args...]"
      }
    },
    "gate-validate": {
      "description": "Route configurable gate validation through skill-system-gate.",
      "input": {
        "rules": {"type": "string", "required": false, "description": "Gate rules path"},
        "artifact_root": {"type": "string", "required": false, "description": "Rule execution root"}
      },
      "output": {
        "description": "Gate validation payload",
        "fields": {"status": "string", "passed": "boolean"}
      },
      "entrypoints": {
        "unix": ["python3", "{skill_dir}/scripts/sk.py", "gate", "validate"]
      }
    },
    "config-get": {
      "description": "Read a config value by dot-path.",
      "input": {
        "key": {"type": "string", "required": true, "description": "Dot-path key to read"}
      },
      "output": {
        "description": "Resolved config value",
        "fields": {"status": "string", "value": "json"}
      },
      "entrypoints": {
        "unix": ["python3", "{skill_dir}/scripts/sk.py", "config", "get", "{key}"],
        "windows": ["python", "{skill_dir}/scripts/sk.py", "config", "get", "{key}"]
      }
    },
    "config-set": {
      "description": "Set a config value by dot-path.",
      "input": {
        "key": {"type": "string", "required": true, "description": "Dot-path key to update"},
        "value": {"type": "string", "required": true, "description": "Value to write"}
      },
      "output": {
        "description": "Updated config confirmation",
        "fields": {"status": "string", "key": "string", "value": "string", "file": "string"}
      },
      "entrypoints": {
        "unix": ["python3", "{skill_dir}/scripts/sk.py", "config", "set", "{key}", "{value}"],
        "windows": ["python", "{skill_dir}/scripts/sk.py", "config", "set", "{key}", "{value}"]
      }
    },
    "tkt-dispatch": {
      "description": "Route any TKT subcommand through the unified CLI.",
      "input": {
        "args": {"type": "string", "required": false, "description": "Pass-through TKT arguments"}
      },
      "output": {
        "description": "Passthrough JSON payload from skill-system-tkt",
        "fields": {"status": "string"}
      },
      "entrypoints": {
        "agent": "Invoke scripts/sk.py with the tkt subcommand family and forward args unchanged"
      }
    },
    "mem-dispatch": {
      "description": "Route any memory subcommand through the unified CLI.",
      "input": {
        "args": {"type": "string", "required": false, "description": "Pass-through memory arguments"}
      },
      "output": {
        "description": "Passthrough JSON payload from skill-system-memory",
        "fields": {"status": "string"}
      },
      "entrypoints": {
        "agent": "Invoke scripts/sk.py with the mem subcommand family and forward args unchanged"
      }
    },
    "install-dispatch": {
      "description": "Route any installer subcommand through the unified CLI.",
      "input": {
        "args": {"type": "string", "required": false, "description": "Pass-through installer arguments"}
      },
      "output": {
        "description": "Passthrough JSON payload from skill-system-installer",
        "fields": {"status": "string"}
      },
      "entrypoints": {
        "agent": "Invoke scripts/sk.py with the install subcommand family and forward args unchanged"
      }
    }
  },
  "stdout_contract": {
    "last_line_json": true,
    "note": "All commands emit JSON on last line. Status is always 'ok' or 'error'."
  }
}
技能管理——列出、添加、状态查看、更新、同步。
skill
{
  "schema_version": "2.0",
  "id": "skill-system-cli",
  "version": "1.0.0",
  "capabilities": [
    "cli-dispatch", "project-init", "project-status",
    "cli-scan", "cli-run", "gate-dispatch",
    "config-read", "config-write",
    "tkt-dispatch", "mem-dispatch", "install-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": "Script stdout/stderr passthrough",
        "fields": {"status": "string"}
      },
      "entrypoints": {
        "agent": "Invoke scripts/sk.py run <script> [args...]"
      }
    },
    "gate-validate": {
      "description": "Route configurable gate validation through skill-system-gate.",
      "input": {
        "rules": {"type": "string", "required": false, "description": "Gate rules path"},
        "artifact_root": {"type": "string", "required": false, "description": "Rule execution root"}
      },
      "output": {
        "description": "Gate validation payload",
        "fields": {"status": "string", "passed": "boolean"}
      },
      "entrypoints": {
        "unix": ["python3", "{skill_dir}/scripts/sk.py", "gate", "validate"]
      }
    },
    "config-get": {
      "description": "Read a config value by dot-path.",
      "input": {
        "key": {"type": "string", "required": true, "description": "Dot-path key to read"}
      },
      "output": {
        "description": "Resolved config value",
        "fields": {"status": "string", "value": "json"}
      },
      "entrypoints": {
        "unix": ["python3", "{skill_dir}/scripts/sk.py", "config", "get", "{key}"],
        "windows": ["python", "{skill_dir}/scripts/sk.py", "config", "get", "{key}"]
      }
    },
    "config-set": {
      "description": "Set a config value by dot-path.",
      "input": {
        "key": {"type": "string", "required": true, "description": "Dot-path key to update"},
        "value": {"type": "string", "required": true, "description": "Value to write"}
      },
      "output": {
        "description": "Updated config confirmation",
        "fields": {"status": "string", "key": "string", "value": "string", "file": "string"}
      },
      "entrypoints": {
        "unix": ["python3", "{skill_dir}/scripts/sk.py", "config", "set", "{key}", "{value}"],
        "windows": ["python", "{skill_dir}/scripts/sk.py", "config", "set", "{key}", "{value}"]
      }
    },
    "tkt-dispatch": {
      "description": "Route any TKT subcommand through the unified CLI.",
      "input": {
        "args": {"type": "string", "required": false, "description": "Pass-through TKT arguments"}
      },
      "output": {
        "description": "Passthrough JSON payload from skill-system-tkt",
        "fields": {"status": "string"}
      },
      "entrypoints": {
        "agent": "Invoke scripts/sk.py with the tkt subcommand family and forward args unchanged"
      }
    },
    "mem-dispatch": {
      "description": "Route any memory subcommand through the unified CLI.",
      "input": {
        "args": {"type": "string", "required": false, "description": "Pass-through memory arguments"}
      },
      "output": {
        "description": "Passthrough JSON payload from skill-system-memory",
        "fields": {"status": "string"}
      },
      "entrypoints": {
        "agent": "Invoke scripts/sk.py with the mem subcommand family and forward args unchanged"
      }
    },
    "install-dispatch": {
      "description": "Route any installer subcommand through the unified CLI.",
      "input": {
        "args": {"type": "string", "required": false, "description": "Pass-through installer arguments"}
      },
      "output": {
        "description": "Passthrough JSON payload from skill-system-installer",
        "fields": {"status": "string"}
      },
      "entrypoints": {
        "agent": "Invoke scripts/sk.py with the install subcommand family and forward args unchanged"
      }
    }
  },
  "stdout_contract": {
    "last_line_json": true,
    "note": "All commands emit JSON on last line. Status is always 'ok' or 'error'."
  }
}