Skip to content
Back to search

agent-skill-sync

Scan, classify (A/B/C/D) and sync AI-agent SKILL.md files across toolchains (Codex, Claude Code, WorkBuddy). Zero-dependency Python CLI.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kina-cmd--agent-skill-sync/badge.svg)](/listings/kina-cmd--agent-skill-sync)

HTML

<a href="/listings/kina-cmd--agent-skill-sync"><img src="/api/listings/kina-cmd--agent-skill-sync/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 174 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # agent-skill-sync
  2. [![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)
  3. [![PyPI version](https://img.shields.io/pypi/v/agent-skill-sync)](https://pypi.org/project/agent-skill-sync/)
  4. [![Python](https://img.shields.io/pypi/pyversions/agent-skill-sync)](https://pypi.org/project/agent-skill-sync/)
  5. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  6. **`skillsync`** — scan, classify and sync AI-agent skills (`SKILL.md` files) across toolchains.
  7. If you use several AI coding agents (OpenAI Codex, Claude Code, WorkBuddy, …), you end up with
  8. skill libraries scattered across different directories, in different layouts, some copied, some
  9. stale, some requiring dependencies you never installed. `skillsync` turns that mess into one
  10. honest inventory — automatically.
  11. Zero dependencies. Pure Python ≥ 3.11 stdlib.
  12. ## What it does
  13. ```
  14. ┌──────────────┐ ┌──────────────┐ ┌────────────────┐
  15. │ ~/.codex/ │ │ marketplace │ │ ~/.claude/ │ … any number of
  16. │ skills/ │ │ plugin cache │ │ skills/ │ source roots
  17. └──────┬───────┘ └──────┬───────┘ └───────┬────────┘
  18. └──────────────┬───┴───────────────────┘
  19. ▼
  20. ┌───────────────┐ classify every skill:
  21. │ scan + parse │ A portable · B missing deps
  22. │ frontmatter │ C rewrite needed · D platform-private
  23. └───────┬───────┘
  24. ▼
  25. ┌───────────────┐ diff against target:
  26. │ INDEX.md │ identical · drifted · missing
  27. │ inventory.json│
  28. └───────┬───────┘
  29. ▼
  30. ┌───────────────┐ optional, safe copy:
  31. │ skillsync sync│ dry-run first, backups, never deletes,
  32. └───────────────┘ skips .venv/.env/node_modules
  33. ```
  34. ### The A/B/C/D migration taxonomy
  35. | Category | Meaning | Action |
  36. |---|---|---|
  37. | **A** | Portable — no platform-private references, every referenced command exists | copy & use |
  38. | **B** | Portable but missing external deps (a CLI, an MCP server) | install deps, then copy |
  39. | **C** | References another agent's conventions (`AGENTS.md`, `image_gen`, …) | rewrite for your target |
  40. | **D** | Bound to the source platform's private runtime | don't migrate |
  41. Classification is heuristic, conservative, and **every decision ships a reason** —
  42. the index shows *why* a skill landed in each bucket, and *which* dependencies are missing
  43. (probed live with `shutil.which` / your `[deps]` table).
  44. ## Install
  45. ```bash
  46. pipx install agent-skill-sync # recommended: isolated CLI install
  47. pip install agent-skill-sync # or into your environment
  48. # from source, without installing:
  49. git clone https://github.com/kina-cmd/agent-skill-sync && cd agent-skill-sync
  50. python -m skillsync.cli --help
  51. ```
  52. ## Usage
  53. ```bash
  54. # What do I have, and in what state?
  55. skillsync status
  56. # One line per skill: category, sync state, source, missing deps
  57. skillsync scan
  58. skillsync scan --category B # only the ones needing deps
  59. skillsync scan --json # machine-readable inventory
  60. # Generate a full index (INDEX.md + inventory.json) you can commit
  61. # or paste into a "tool reuse" skill for your agent to read
  62. skillsync index --out ./output --lang zh
  63. # What changed upstream since I last looked?
  64. skillsync check # diffs against the last snapshot, then records a new one
  65. skillsync check --quiet # summary line only (cron-friendly)
  66. # Sync portable skills into the target root — plan first, always
  67. skillsync sync --dry-run
  68. skillsync sync --categories A
  69. skillsync sync --categories A,B --force # update drifted copies (backs them up)
  70. ```
  71. ### Sync safety rules
  72. * Never overwrites without `--force`; a forced update first moves the old copy to
  73. `<target>/.skillsync-backup/` — nothing is ever deleted.
  74. * `.venv/`, `.env`, `node_modules/`, `__pycache__/` are always excluded from copies,
  75. so secrets and 500 MB virtualenvs never travel silently.
  76. * `--dry-run` prints the exact plan and touches nothing.
  77. ## Configuration
  78. By default, `skillsync` auto-discovers the well-known roots on your machine —
  79. every major adopter of the [Agent Skills open standard](https://agentskills.io):
  80. | Root | Platform |
  81. |---|---|
  82. | `~/.codex/skills` + `~/.codex/plugins/cache` | OpenAI Codex (+ marketplace plugin caches) |
  83. | `~/.claude/skills` | Claude Code (reference implementation) |
  84. | `~/.copilot/skills` | GitHub Copilot |
  85. | `~/.gemini/skills` | Gemini CLI |
  86. | `~/.cursor/skills` | Cursor |
  87. | `~/.config/opencode/skills` | OpenCode |
  88. Target defaults to `~/.workbuddy/skills`. Roots that don't exist are skipped silently.
  89. Override or extend with `skillsync.toml` (looked up in `./` then `$XDG_CONFIG_HOME/skillsync/`):
  90. ```toml
  91. [target]
  92. label = "workbuddy"
  93. path = "~/.workbuddy/skills"
  94. [[sources]]
  95. label = "codex"
  96. path = "~/.codex/skills"
  97. [[sources]]
  98. label = "codex-marketplace"
  99. path = "~/.codex/plugins/cache"
  100. glob = "**/skills/*/SKILL.md"
  101. [[sources]]
  102. label = "codex-system"
  103. path = "~/.codex/skills/.system"
  104. system = true # platform-private → always category D
  105. [deps]
  106. # Teach the classifier that a dep is satisfied even if not on PATH:
  107. voicebox = { kind = "path", value = "~/App/Voicebox/voicebox.exe" }
  108. ffmpeg = "ffmpeg" # shorthand: check PATH
  109. notion = { kind = "env", value = "NOTION_TOKEN" } # check env var
  110. ```
  111. See [`skillsync.example.toml`](skillsync.example.toml) for a complete example.
  112. ## Typical workflow: keeping an index skill fresh
  113. Many people maintain a hand-written "local tool reuse" index for their agent.
  114. It rots the moment a skill is added upstream. Instead:
  115. ```bash
  116. skillsync index --out ~/.workbuddy/skills/local-tool-reuse/generated --lang zh
  117. ```
  118. …on a schedule or a git hook, and let the agent read a generated file that is
  119. always true. `inventory.json` is stable, machine-readable output for further tooling.
  120. ## Development
  121. ```bash
  122. python -m unittest discover tests -v
  123. ```
  124. ## Design notes
  125. * **No PyYAML.** The frontmatter parser implements exactly the YAML subset skill
  126. files use (scalars, folded/literal blocks, inline and block lists), and fails soft —
  127. unparsable lines become warnings, never crashes.
  128. * **No network.** Everything is local filesystem inspection.
  129. * **Qualified names.** Marketplace plugin caches nest skills as
  130. `<plugin>/<version>/skills/<name>/`; these are reported as `plugin:name` so
  131. collisions are visible.
  132. ## License
  133. MIT © 2026 kina-cmd

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.