Yibi Skills Sync

@yibi/skills-sync is a background CLI for capturing local agent skill changes into a Git audit monorepo. Git is the source of truth. Optional ingest can run after commits through a shell command adapter or the KB upload API.

Install

npm install -g @yibi/skills-sync

For local development from this repo:

npm link

Quick Start

yibi-skills probe --json
yibi-skills init --preset local-agent-common
yibi-skills config validate
yibi-skills snapshot
yibi-skills bootstrap --json
yibi-skills watch

For portable setup, use the bundled skills/yibi-skills-bootstrap skill. The skill instructs the device-local agent to run probe, write an explicit sourceRoots config for that machine, then call snapshot and bootstrap.

Agent Handover Setup

When handing this project to an agent on a new machine, keep the setup linear and evidence-based. Use the default paths unless the user gives explicit portable paths:

yibi-skills probe --json
yibi-skills init --preset local-agent-common
yibi-skills config validate
yibi-skills snapshot
yibi-skills bootstrap --json
yibi-skills service install
yibi-skills service start
yibi-skills service status --json

Stop if config validate fails, if bootstrap reports no usable snapshot skills, or if service status --json reports configValid: false. service install writes a user service for the resolved config, state dir, and monorepo; service start starts the watcher. On macOS this is a launchd user agent, and on Linux this is a systemd --user unit.

For a portable handover under ~/.yibi, keep the same flags on every command so the service points at the same runtime state:

yibi-skills probe --json
yibi-skills init --preset local-agent-common --config ~/.yibi/skills-sync/config.json --state-dir ~/.yibi/skills-sync --monorepo ~/.yibi/skills-monorepo
yibi-skills config validate --config ~/.yibi/skills-sync/config.json --state-dir ~/.yibi/skills-sync --monorepo ~/.yibi/skills-monorepo
yibi-skills snapshot --config ~/.yibi/skills-sync/config.json --state-dir ~/.yibi/skills-sync --monorepo ~/.yibi/skills-monorepo
yibi-skills bootstrap --config ~/.yibi/skills-sync/config.json --state-dir ~/.yibi/skills-sync --monorepo ~/.yibi/skills-monorepo --json
yibi-skills service install --config ~/.yibi/skills-sync/config.json --state-dir ~/.yibi/skills-sync --monorepo ~/.yibi/skills-monorepo
yibi-skills service start --config ~/.yibi/skills-sync/config.json --state-dir ~/.yibi/skills-sync --monorepo ~/.yibi/skills-monorepo
yibi-skills service status --json --config ~/.yibi/skills-sync/config.json --state-dir ~/.yibi/skills-sync --monorepo ~/.yibi/skills-monorepo

Default paths:

• Config: ~/.config/yibi-skills-sync/config.json
• State: ~/.local/state/yibi-skills-sync
• Audit monorepo: ~/.local/share/yibi-skills-sync/skills-monorepo

Override with --config, --state-dir, --monorepo, or environment variables:

• YIBI_SKILLS_SYNC_CONFIG
• YIBI_SKILLS_STATE_DIR
• YIBI_SKILLS_MONOREPO

Configuration

{
  "sourceRoots": [
    { "path": "~/.codex/skills", "sourceSystem": "codex-skills", "tier": "live", "depth": 1 },
    { "path": "~/.agents/skills", "sourceSystem": "agent-skills", "tier": "live", "depth": 1 },
    { "path": "~/.hermes/skills", "sourceSystem": "hermes-skills", "tier": "live", "depth": 3 }
  ],
  "monorepo": { "path": "~/.local/share/yibi-skills-sync/skills-monorepo" },
  "review": { "mode": "manual" },
  "ingest": { "enabled": false, "command": "" },
  "watch": { "intervalSeconds": 2, "ignore": [] }
}

When ingest.enabled is false, commits are still recorded in Git and ingest is marked skipped in state.

To enable an existing ingest pipeline:

{
  "ingest": {
    "enabled": true,
    "command": "python3 /path/to/ingest.py --monorepo {monorepo} --commit {commit} --load --json",
    "dryRunCommand": "python3 /path/to/ingest.py --monorepo {monorepo} --commit {commit} --load --dry-run-ingest --json"
  }
}

Available placeholders: {commit}, {monorepo}, {stateDir}.

To upload accepted monorepo commits through the KB Multipart Upload API:

{
  "ingest": {
    "enabled": true,
    "type": "kb-upload-api",
    "baseUrl": "http://127.0.0.1:18080",
    "tokenEnv": "KB_UPLOAD_API_TOKEN",
    "sourceSystem": "yibi-skills-sync"
  }
}

Set the token outside the config when possible:

export KB_UPLOAD_API_TOKEN='kbup_...'
yibi-skills retry-ingest --commit HEAD --dry-run-ingest --json

--dry-run-ingest sends metadata.preflight=true to the upload API. The adapter records the returned job_id, status_url, and result_url in local state.

Commands

yibi-skills init
yibi-skills probe --json
yibi-skills config validate
yibi-skills snapshot
yibi-skills bootstrap --json
yibi-skills capture --path ~/.codex/skills/example/SKILL.md
yibi-skills status --json
yibi-skills review --json
yibi-skills commit --json
yibi-skills retry-ingest --commit HEAD --json
yibi-skills service install
yibi-skills service start

watch uses short polling over the configured skill roots and the current state baseline. Each polling cycle re-discovers the configured roots, so newly created skill directories are picked up automatically and recorded as dirty changes. It still does not commit unless you run the review/commit command.

Use capture --path ... when you want to force an immediate one-off capture for a specific path instead of waiting for the next poll cycle.

Service Management

macOS uses launchd user agents. Linux uses systemd --user units.

yibi-skills service install
yibi-skills service start
yibi-skills service status
yibi-skills service stop
yibi-skills service uninstall

Development

npm test
python3 -m pytest test

The Python engine is vendored under python/ for V1 to preserve the existing scan/diff/review behavior while the CLI provides packaging, config, and service management.