agent-skill-sync 0.1.0__py3-none-any.whl

agent_skill_sync-0.1.0.dist-info/METADATA

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: agent-skill-sync
+Version: 0.1.0
+Summary: Scan, classify and sync AI-agent skills (SKILL.md) across toolchains like OpenAI Codex, Claude Code and WorkBuddy.
+License: MIT
+Project-URL: Homepage, https://github.com/kina-cmd/agent-skill-sync
+Project-URL: Issues, https://github.com/kina-cmd/agent-skill-sync/issues
+Keywords: ai,agent,skills,codex,claude,workbuddy,migration,inventory
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# agent-skill-sync
+
+[![CI](https://github.com/kina-cmd/agent-skill-sync/actions/workflows/ci.yml/badge.svg)](https://github.com/kina-cmd/agent-skill-sync/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/agent-skill-sync)](https://pypi.org/project/agent-skill-sync/)
+[![Python](https://img.shields.io/pypi/pyversions/agent-skill-sync)](https://pypi.org/project/agent-skill-sync/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**`skillsync`** — scan, classify and sync AI-agent skills (`SKILL.md` files) across toolchains.
+
+If you use several AI coding agents (OpenAI Codex, Claude Code, WorkBuddy, …), you end up with
+skill libraries scattered across different directories, in different layouts, some copied, some
+stale, some requiring dependencies you never installed. `skillsync` turns that mess into one
+honest inventory — automatically.
+
+Zero dependencies. Pure Python ≥ 3.11 stdlib.
+
+## What it does
+
+```
+┌──────────────┐   ┌──────────────┐   ┌────────────────┐
+│ ~/.codex/    │   │ marketplace  │   │ ~/.claude/     │   … any number of
+│   skills/    │   │ plugin cache │   │   skills/      │       source roots
+└──────┬───────┘   └──────┬───────┘   └───────┬────────┘
+       └──────────────┬───┴───────────────────┘
+                      ▼
+              ┌───────────────┐     classify every skill:
+              │  scan + parse │     A portable · B missing deps
+              │  frontmatter  │     C rewrite needed · D platform-private
+              └───────┬───────┘
+                      ▼
+              ┌───────────────┐     diff against target:
+              │ INDEX.md      │     identical · drifted · missing
+              │ inventory.json│
+              └───────┬───────┘
+                      ▼
+              ┌───────────────┐     optional, safe copy:
+              │ skillsync sync│     dry-run first, backups, never deletes,
+              └───────────────┘     skips .venv/.env/node_modules
+```
+
+### The A/B/C/D migration taxonomy
+
+| Category | Meaning | Action |
+|---|---|---|
+| **A** | Portable — no platform-private references, every referenced command exists | copy & use |
+| **B** | Portable but missing external deps (a CLI, an MCP server) | install deps, then copy |
+| **C** | References another agent's conventions (`AGENTS.md`, `image_gen`, …) | rewrite for your target |
+| **D** | Bound to the source platform's private runtime | don't migrate |
+
+Classification is heuristic, conservative, and **every decision ships a reason** —
+the index shows *why* a skill landed in each bucket, and *which* dependencies are missing
+(probed live with `shutil.which` / your `[deps]` table).
+
+## Install
+
+```bash
+pipx install agent-skill-sync   # recommended: isolated CLI install
+pip install agent-skill-sync    # or into your environment
+
+# from source, without installing:
+git clone https://github.com/kina-cmd/agent-skill-sync && cd agent-skill-sync
+python -m skillsync.cli --help
+```
+
+## Usage
+
+```bash
+# What do I have, and in what state?
+skillsync status
+
+# One line per skill: category, sync state, source, missing deps
+skillsync scan
+skillsync scan --category B          # only the ones needing deps
+skillsync scan --json                # machine-readable inventory
+
+# Generate a full index (INDEX.md + inventory.json) you can commit
+# or paste into a "tool reuse" skill for your agent to read
+skillsync index --out ./output --lang zh
+
+# Sync portable skills into the target root — plan first, always
+skillsync sync --dry-run
+skillsync sync --categories A
+skillsync sync --categories A,B --force    # update drifted copies (backs them up)
+```
+
+### Sync safety rules
+
+* Never overwrites without `--force`; a forced update first moves the old copy to
+  `<target>/.skillsync-backup/` — nothing is ever deleted.
+* `.venv/`, `.env`, `node_modules/`, `__pycache__/` are always excluded from copies,
+  so secrets and 500 MB virtualenvs never travel silently.
+* `--dry-run` prints the exact plan and touches nothing.
+
+## Configuration
+
+By default, `skillsync` auto-discovers the well-known roots on your machine
+(`~/.codex/skills`, `~/.codex/plugins/cache`, `~/.claude/skills` → target `~/.workbuddy/skills`).
+
+Override or extend with `skillsync.toml` (looked up in `./` then `$XDG_CONFIG_HOME/skillsync/`):
+
+```toml
+[target]
+label = "workbuddy"
+path  = "~/.workbuddy/skills"
+
+[[sources]]
+label = "codex"
+path  = "~/.codex/skills"
+
+[[sources]]
+label = "codex-marketplace"
+path  = "~/.codex/plugins/cache"
+glob  = "**/skills/*/SKILL.md"
+
+[[sources]]
+label  = "codex-system"
+path   = "~/.codex/skills/.system"
+system = true              # platform-private → always category D
+
+[deps]
+# Teach the classifier that a dep is satisfied even if not on PATH:
+voicebox = { kind = "path", value = "~/App/Voicebox/voicebox.exe" }
+ffmpeg   = "ffmpeg"                                   # shorthand: check PATH
+notion   = { kind = "env",  value = "NOTION_TOKEN" }  # check env var
+```
+
+See [`skillsync.example.toml`](skillsync.example.toml) for a complete example.
+
+## Typical workflow: keeping an index skill fresh
+
+Many people maintain a hand-written "local tool reuse" index for their agent.
+It rots the moment a skill is added upstream. Instead:
+
+```bash
+skillsync index --out ~/.workbuddy/skills/local-tool-reuse/generated --lang zh
+```
+
+…on a schedule or a git hook, and let the agent read a generated file that is
+always true. `inventory.json` is stable, machine-readable output for further tooling.
+
+## Development
+
+```bash
+python -m unittest discover tests -v
+```
+
+## Design notes
+
+* **No PyYAML.** The frontmatter parser implements exactly the YAML subset skill
+  files use (scalars, folded/literal blocks, inline and block lists), and fails soft —
+  unparsable lines become warnings, never crashes.
+* **No network.** Everything is local filesystem inspection.
+* **Qualified names.** Marketplace plugin caches nest skills as
+  `<plugin>/<version>/skills/<name>/`; these are reported as `plugin:name` so
+  collisions are visible.
+
+## License
+
+MIT © 2026 kina-cmd

agent_skill_sync-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+agent_skill_sync-0.1.0.dist-info/licenses/LICENSE,sha256=n1B3Z60LqfKo9lza_o3mpIDQVobpzJzs1Ezutf9ClZA,1065
+skillsync/__init__.py,sha256=Zmx5Ezy0OZcDbZAQ7t_b2HksCg_BO9ahiM0xAQpCU20,409
+skillsync/classifier.py,sha256=c-C-dNJu1-ZafXiKSfh8sUSEIonVfmf_XaCXvkZM0Ek,6895
+skillsync/cli.py,sha256=sTpuL73JktAbNyfU8UCv2DYoWxpKnx9J4ca8dsGGr9E,8803
+skillsync/config.py,sha256=OjRaKkEPY1tlILtfkiRAbEJE2nxCZgJHjgQaVHhOV90,5767
+skillsync/differ.py,sha256=dfWwmu18QlSB9jWyr_-XNTpipc5nENyA2IpUc-K6HxI,3030
+skillsync/frontmatter.py,sha256=VrYwM5XQtsFddpbH3mP838dJcVHcpmzr3OCRc55854g,8592
+skillsync/model.py,sha256=7sljjgsq82tmGnvMhS2T_7r9sgEIisX7yCMApdQrv-0,3018
+skillsync/report.py,sha256=cNrvGXIfNSauczNdVTkTj9IdGf3Hz7Zui97EhhJ3YkA,5458
+skillsync/resolve.py,sha256=HwOc9jhHVe_GU5AlRQOEe7vFo4qhHDzfAHWv_6exXbk,4390
+skillsync/scanner.py,sha256=SAjvGqmIbcXp-D0UN9ofcrXDSfqGdXQWOy8u198DNX0,3220
+skillsync/sync.py,sha256=sMx6mtJ1FE6SLzIe80O05KtMMQGsPfL56xvKDrLx5Es,5867
+agent_skill_sync-0.1.0.dist-info/METADATA,sha256=xbeTT6Hm6Pvelu-tCEmM_OoTnGb7YNSjVI67OxX5i4I,7578
+agent_skill_sync-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+agent_skill_sync-0.1.0.dist-info/entry_points.txt,sha256=PxGra8xJCTZ0yhL3ZvUnTfdRLtWkKpmuZGpYjyoBTlE,49
+agent_skill_sync-0.1.0.dist-info/top_level.txt,sha256=xsxa0clwU4aCjkV2dCfN83oLJ9B5Hxfh-bseAMlgl9I,10
+agent_skill_sync-0.1.0.dist-info/RECORD,,

agent_skill_sync-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agent_skill_sync-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+skillsync = skillsync.cli:main

agent_skill_sync-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kina-cmd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_skill_sync-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+skillsync

skillsync/__init__.py

@@ -0,0 +1,11 @@
+"""skillsync — scan, classify and sync agent skills between toolchains.
+
+A dependency-free toolkit for people who accumulate AI-agent "skills"
+(SKILL.md files) across several CLIs — OpenAI Codex, Claude Code, WorkBuddy,
+etc. — and want one honest inventory: what exists, where it lives, whether it
+is runnable, and what it would take to migrate it.
+"""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

skillsync/classifier.py

@@ -0,0 +1,161 @@
+"""Classifier: assign each skill an A/B/C/D migration category, automatically.
+
+The taxonomy:
+
+* **A — portable.** Nothing platform-private, every referenced external command
+  is present on this machine. Can be copied to the target and used as-is.
+* **B — needs dependencies.** Portable in spirit, but references CLIs / MCP
+  servers / runtimes that are *missing* here. Runnable once deps are installed.
+* **C — rewrite required.** References another agent's config conventions or
+  tool-call vocabulary (``AGENTS.md``, ``image_gen``, ``tool_search``…) that has
+  no drop-in equivalent. Methodology is reusable, the text is not.
+* **D — platform-private.** Bound to the source runtime's internals (Codex
+  system skills, in-app browser control, codex-security, plugin management).
+  Do not migrate.
+
+Classification is heuristic and intentionally conservative: when a skill
+matches both a "private" marker and a missing dependency, the stronger
+constraint wins (D > C > B > A). Every decision carries a human-readable
+``reason`` and the concrete ``missing_deps`` so the index can show *why*.
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+
+from .config import Config
+from .model import Skill
+
+# Tokens that look like shell commands worth checking with shutil.which().
+# We only probe a curated allowlist to avoid false positives from prose.
+_KNOWN_COMMANDS = {
+    "ffmpeg", "ffprobe", "node", "npx", "pnpm", "yarn", "npm", "python", "python3",
+    "pip", "pipx", "uv", "git", "gh", "rg", "fd", "jq", "yt-dlp", "playwright",
+    "manim", "hf", "heygen", "codex", "docker", "magick", "convert", "sox",
+    "browser-act", "mcporter", "arkcli", "openmontage", "voicebox", "genmedia",
+}
+
+# MCP server references look like mcp__<server>__<tool> or "MCP server <name>".
+_MCP_RE = re.compile(r"\bmcp__([a-z0-9_\-]+)__", re.IGNORECASE)
+_MCP_PROSE_RE = re.compile(r"\b([A-Za-z0-9_\-]+)\s+MCP\b")
+# Prose matches are noisy ("the detailed MCP", "an s MCP client"...), so a prose
+# token only counts as a server name if it is hyphenated/underscored or in this
+# allowlist of servers commonly referenced in skills.
+_MCP_PROSE_ALLOWLIST = {
+    "notion", "firecrawl", "playwright", "devtools", "browser", "browserbase",
+    "scrapling", "voicebox", "linear", "gmail", "heygen", "chrome", "puppeteer",
+    "sheetagent", "github", "memory", "filesystem", "sequential-thinking",
+    "aitoearn", "hf_jobs", "codex_apps", "context7", "supabase", "sentry",
+}
+
+# Words that signal "this is just methodology, but it talks to another agent".
+_C_MARKERS = (
+    "AGENTS.md", "CLAUDE.md", "--tools codex", "image_gen", "view_image",
+    "tool_search", "toolsearch", "present-artifact", "/plugin", "claude code",
+    "control-in-app-browser", "in-app browser",
+)
+
+# Words that signal platform-private internals — never migrate.
+_D_MARKERS = (
+    "codex-security", "computer-use", "control-chrome", "sites:sites-hosting",
+    "sites:sites-building", "publish-artifact-to-sites", "plugin-creator",
+    "skill-installer", "plugin-management", "scan id", "scanid",
+    "documents:documents", "spreadsheets:excel-live-control",
+    "template-creator",
+)
+
+
+def _referenced_commands(text: str) -> set[str]:
+    found: set[str] = set()
+    # fenced code blocks and inline `code` are the most reliable signal
+    for chunk in re.findall(r"```.*?```", text, flags=re.DOTALL):
+        for word in re.findall(r"\b([a-z0-9_\-]+)\b", chunk):
+            if word in _KNOWN_COMMANDS:
+                found.add(word)
+    for chunk in re.findall(r"`([^`]+)`", text):
+        first = chunk.strip().split()[0] if chunk.strip() else ""
+        if first in _KNOWN_COMMANDS:
+            found.add(first)
+    return found
+
+
+def _referenced_mcp(text: str) -> set[str]:
+    found = {m.lower() for m in _MCP_RE.findall(text)}
+    for token in _MCP_PROSE_RE.findall(text):
+        t = token.lower()
+        if t in _MCP_PROSE_ALLOWLIST or "-" in t or "_" in t:
+            found.add(t)
+    # Drop generic words that the prose regex over-captures.
+    return {
+        m for m in found
+        if m not in {"the", "a", "an", "use", "call", "via", "with", "and", "or", "s", "to", "of"}
+        and len(m) > 1
+    }
+
+
+def classify(skill: Skill, config: Config) -> Skill:
+    """Mutate and return ``skill`` with category/reason/missing_deps set."""
+    try:
+        text = skill.path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        text = ""
+    low = text.lower()
+
+    # --- D: platform-private -------------------------------------------------
+    if skill.source.endswith("-system") or ".system" in str(skill.path):
+        skill.category = "D"
+        skill.category_reason = "lives in a platform .system root (private runtime skill)"
+        return skill
+    for marker in _D_MARKERS:
+        if marker.lower() in low:
+            skill.category = "D"
+            skill.category_reason = f"references platform-private internal '{marker}'"
+            return skill
+    for marker in config.platform_private_markers:
+        if marker.lower() in low and marker.lower() in {m.lower() for m in _D_MARKERS}:
+            skill.category = "D"
+            skill.category_reason = f"references platform-private internal '{marker}'"
+            return skill
+
+    # --- deps: missing external commands / MCP servers -----------------------
+    missing: list[str] = []
+    for cmd in sorted(_referenced_commands(text)):
+        # 'python'/'python3' are ubiquitous; only flag if truly absent.
+        if shutil.which(cmd) is None:
+            missing.append(cmd)
+    for server in sorted(_referenced_mcp(text)):
+        # A configured dep in the [deps] table can vouch for an MCP server.
+        dep = config.deps.get(server)
+        if dep is not None and dep.available():
+            continue
+        missing.append(f"MCP:{server}")
+
+    # --- C: needs rewrite for the target agent ------------------------------
+    c_hits = [m for m in _C_MARKERS if m.lower() in low]
+    if c_hits:
+        skill.category = "C"
+        skill.category_reason = (
+            "references another agent's conventions/tools (" + ", ".join(sorted(set(c_hits))[:4]) + "); "
+            "methodology reusable, text must be rewritten for the target"
+        )
+        skill.missing_deps = missing
+        return skill
+
+    # --- B: portable but missing deps ---------------------------------------
+    if missing:
+        skill.category = "B"
+        skill.category_reason = "portable, but missing external dependencies"
+        skill.missing_deps = missing
+        return skill
+
+    # --- A: portable and runnable -------------------------------------------
+    skill.category = "A"
+    skill.category_reason = "no platform-private references and all commands present"
+    skill.missing_deps = []
+    return skill
+
+
+def classify_all(skills, config: Config) -> None:
+    for skill in skills:
+        classify(skill, config)

skillsync/cli.py

@@ -0,0 +1,218 @@
+"""Command-line interface for skillsync."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections import Counter
+from pathlib import Path
+
+from . import __version__
+from .classifier import classify_all
+from .config import load_config
+from .differ import diff_all, sync_state
+from .model import CATEGORIES
+from .report import to_markdown, write_outputs
+from .resolve import resolve
+from .scanner import scan
+from .sync import execute_sync, plan_sync
+
+
+def _prepare(cfg, *, dedupe: bool = False):
+    """Scan → classify → diff → (optionally) resolve cross-source duplicates."""
+    result = scan(cfg)
+    classify_all(result.skills, cfg)
+    diff_all(result.skills, cfg)
+    if dedupe:
+        skills, dups, shadowed = resolve(result.skills)
+        result.skills = skills
+        result.duplicates = dups
+        result.shadowed = shadowed
+        result.resolved = True
+    return result
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="skillsync",
+        description="Scan, classify and sync AI-agent skills across toolchains.",
+    )
+    parser.add_argument("--version", action="version", version=f"skillsync {__version__}")
+    parser.add_argument("--config", help="path to a skillsync.toml")
+    parser.add_argument(
+        "--dedupe",
+        action="store_true",
+        help="collapse skills that are identical across multiple source roots into one entry",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_scan = sub.add_parser("scan", help="scan roots and print a one-line-per-skill summary")
+    p_scan.add_argument("--source", action="append", help="extra source root label=path")
+    p_scan.add_argument("--category", choices=[*CATEGORIES, "?"], help="filter by category")
+    p_scan.add_argument("--json", action="store_true", help="emit JSON inventory")
+
+    p_status = sub.add_parser("status", help="show counts and sync state (missing/drifted/identical)")
+
+    p_index = sub.add_parser("index", help="generate INDEX.md + inventory.json")
+    p_index.add_argument("--out", default=".", help="output directory (default: cwd)")
+    p_index.add_argument("--lang", choices=["zh", "en"], default="zh")
+
+    p_sync = sub.add_parser("sync", help="copy portable skills into the target root")
+    p_sync.add_argument("--categories", default="A", help="comma list, e.g. A,B (default: A)")
+    p_sync.add_argument("--dry-run", action="store_true", help="print the plan, change nothing")
+    p_sync.add_argument("--force", action="store_true", help="update drifted copies (backs them up first)")
+    p_sync.add_argument("--prefix", default="", help="prefix added to every synced skill name")
+    p_sync.add_argument(
+        "--drifted-only",
+        action="store_true",
+        help="only refresh skills that already exist in the target but differ; never add new ones",
+    )
+    p_sync.add_argument("--source", action="append", help="restrict sync to these source labels (repeatable)")
+
+    return parser
+
+
+def _apply_extra_sources(cfg, extras: list[str] | None) -> None:
+    if not extras:
+        return
+    from .config import DEFAULT_GLOB, SourceRoot
+
+    for item in extras:
+        if "=" not in item:
+            print(f"[warn] ignoring --source without '=': {item}", file=sys.stderr)
+            continue
+        label, _, path = item.partition("=")
+        cfg.sources.append(
+            SourceRoot(label=label.strip(), path=Path(path.strip()).expanduser(), glob=DEFAULT_GLOB)
+        )
+
+
+def _do_scan(cfg, args) -> int:
+    result = _prepare(cfg, dedupe=getattr(args, "dedupe", False))
+    if args.json:
+        from .report import to_json
+
+        print(to_json(result))
+        return 0
+    skills = result.skills
+    if getattr(args, "category", None):
+        skills = [s for s in skills if s.category == args.category]
+    for s in sorted(skills, key=lambda x: (x.category, x.source, x.name)):
+        state = sync_state(s)
+        deps = (" [" + ",".join(s.missing_deps) + "]") if s.missing_deps else ""
+        print(f"{s.category}  {state:9}  {s.source:18} {s.name}{deps}")
+    counts = Counter(s.category for s in result.skills)
+    print(
+        f"\n{len(result.skills)} skills | "
+        + " ".join(f"{c}={counts.get(c, 0)}" for c in CATEGORIES)
+        + (f" ?={counts.get('?', 0)}" if counts.get("?") else "")
+    )
+    if result.errors:
+        print(f"{len(result.errors)} warning(s); rerun with --json for detail", file=sys.stderr)
+    return 0
+
+
+def _do_status(cfg, args) -> int:
+    result = _prepare(cfg, dedupe=getattr(args, "dedupe", False))
+    counts = Counter(s.category for s in result.skills)
+    sync_counts = Counter(sync_state(s) for s in result.skills)
+    print("skillsync status")
+    print("================")
+    if cfg.target:
+        print(f"target: {cfg.target.label} -> {cfg.target.path} ({'exists' if cfg.target.path.is_dir() else 'MISSING'})")
+    for label, path in result.roots_scanned:
+        n = sum(1 for s in result.skills if s.source == label)
+        print(f"source: {label:20} {n:3} skills   {path}")
+    print("\nby category:")
+    for c in (*CATEGORIES, "?"):
+        if counts.get(c):
+            print(f"  {c}: {counts[c]}")
+    print("\nsync state:")
+    for state in ("identical", "drifted", "missing"):
+        print(f"  {state:10}: {sync_counts.get(state, 0)}")
+    drifted = [s for s in result.skills if sync_state(s) == "drifted"]
+    if drifted:
+        print("\ndrifted (source != target):")
+        for s in sorted(drifted, key=lambda x: x.name)[:40]:
+            print(f"  - {s.name}")
+        if len(drifted) > 40:
+            print(f"  ... and {len(drifted) - 40} more")
+    if result.resolved and result.duplicates:
+        print(f"\ndedupe: collapsed {len(result.duplicates)} name(s) identical across roots "
+              f"(e.g. {result.duplicates[0][0]}: {', '.join(result.duplicates[0][1])})")
+    if result.resolved and result.shadowed:
+        print(f"dedupe: shadowed {len(result.shadowed)} stale copy/copies superseded by a "
+              f"newer canonical version (kept the higher-priority source)")
+    return 0
+
+
+def _do_index(cfg, args) -> int:
+    result = _prepare(cfg, dedupe=getattr(args, "dedupe", False))
+    out_dir = Path(args.out).expanduser()
+    paths = write_outputs(result, out_dir, lang=args.lang)
+    for p in paths:
+        print(f"wrote {p}")
+    # Also echo the markdown to stdout for quick piping.
+    print()
+    print(to_markdown(result, lang=args.lang)[:2000])
+    return 0
+
+
+def _do_sync(cfg, args) -> int:
+    if cfg.target is None or not cfg.target.path.is_dir():
+        print("[error] target root missing; set [target] in skillsync.toml", file=sys.stderr)
+        return 2
+    result = _prepare(cfg, dedupe=getattr(args, "dedupe", False))
+    cats = tuple(c.strip().upper() for c in args.categories.split(",") if c.strip())
+    collisions = {s.name for s in result.skills if s.name.startswith(args.prefix)} if args.prefix else set()
+    report = plan_sync(
+        result.skills,
+        cfg.target.path,
+        categories=cats,
+        prefix_collisions=collisions,
+        force=args.force,
+        name_prefix=args.prefix,
+        drifted_only=args.drifted_only,
+        sources=tuple(args.source) if args.source else None,
+    )
+    mode = "DRY RUN" if args.dry_run else "SYNC"
+    print(f"{mode}: categories={'+'.join(cats)} target={cfg.target.path}")
+    for item in report.planned:
+        print(f"  [{item.action}] {item.skill.name} -> {item.dest}  {item.note}")
+    for item in report.skipped:
+        print(f"  [skip]  {item.skill.name}  ({item.note})")
+    if not report.planned:
+        print("  nothing to do.")
+        return 0
+    if args.dry_run:
+        print(f"\ndry run: {len(report.planned)} action(s) would run. Re-run without --dry-run to apply.")
+        return 0
+    execute_sync(report, cfg.target.path, dry_run=False)
+    print(f"\ncopied={len(report.copied)} updated={len(report.updated)} errors={len(report.errors)}")
+    for b in report.backed_up:
+        print(f"  backed up -> {b}")
+    for e in report.errors:
+        print(f"  [error] {e}", file=sys.stderr)
+    return 1 if report.errors else 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    cfg = load_config(args.config)
+    # --source means "add a source root" only for scan; for sync it filters by
+    # existing labels, so we must not treat sync's values as new roots.
+    if args.command == "scan":
+        _apply_extra_sources(cfg, getattr(args, "source", None))
+
+    handlers = {
+        "scan": _do_scan,
+        "status": _do_status,
+        "index": _do_index,
+        "sync": _do_sync,
+    }
+    return handlers[args.command](cfg, args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())