agent-skill-sync 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- agent_skill_sync-0.1.0/LICENSE +21 -0
- agent_skill_sync-0.1.0/PKG-INFO +182 -0
- agent_skill_sync-0.1.0/README.md +159 -0
- agent_skill_sync-0.1.0/agent_skill_sync.egg-info/PKG-INFO +182 -0
- agent_skill_sync-0.1.0/agent_skill_sync.egg-info/SOURCES.txt +20 -0
- agent_skill_sync-0.1.0/agent_skill_sync.egg-info/dependency_links.txt +1 -0
- agent_skill_sync-0.1.0/agent_skill_sync.egg-info/entry_points.txt +2 -0
- agent_skill_sync-0.1.0/agent_skill_sync.egg-info/top_level.txt +1 -0
- agent_skill_sync-0.1.0/pyproject.toml +35 -0
- agent_skill_sync-0.1.0/setup.cfg +4 -0
- agent_skill_sync-0.1.0/skillsync/__init__.py +11 -0
- agent_skill_sync-0.1.0/skillsync/classifier.py +161 -0
- agent_skill_sync-0.1.0/skillsync/cli.py +218 -0
- agent_skill_sync-0.1.0/skillsync/config.py +185 -0
- agent_skill_sync-0.1.0/skillsync/differ.py +98 -0
- agent_skill_sync-0.1.0/skillsync/frontmatter.py +260 -0
- agent_skill_sync-0.1.0/skillsync/model.py +78 -0
- agent_skill_sync-0.1.0/skillsync/report.py +134 -0
- agent_skill_sync-0.1.0/skillsync/resolve.py +114 -0
- agent_skill_sync-0.1.0/skillsync/scanner.py +90 -0
- agent_skill_sync-0.1.0/skillsync/sync.py +155 -0
- agent_skill_sync-0.1.0/tests/test_skillsync.py +344 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 kina-cmd
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: agent-skill-sync
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Scan, classify and sync AI-agent skills (SKILL.md) across toolchains like OpenAI Codex, Claude Code and WorkBuddy.
|
|
5
|
+
License: MIT
|
|
6
|
+
Project-URL: Homepage, https://github.com/kina-cmd/agent-skill-sync
|
|
7
|
+
Project-URL: Issues, https://github.com/kina-cmd/agent-skill-sync/issues
|
|
8
|
+
Keywords: ai,agent,skills,codex,claude,workbuddy,migration,inventory
|
|
9
|
+
Classifier: Development Status :: 3 - Alpha
|
|
10
|
+
Classifier: Environment :: Console
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
17
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
18
|
+
Classifier: Topic :: Utilities
|
|
19
|
+
Requires-Python: >=3.11
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
License-File: LICENSE
|
|
22
|
+
Dynamic: license-file
|
|
23
|
+
|
|
24
|
+
# agent-skill-sync
|
|
25
|
+
|
|
26
|
+
[](https://github.com/kina-cmd/agent-skill-sync/actions/workflows/ci.yml)
|
|
27
|
+
[](https://pypi.org/project/agent-skill-sync/)
|
|
28
|
+
[](https://pypi.org/project/agent-skill-sync/)
|
|
29
|
+
[](LICENSE)
|
|
30
|
+
|
|
31
|
+
**`skillsync`** — scan, classify and sync AI-agent skills (`SKILL.md` files) across toolchains.
|
|
32
|
+
|
|
33
|
+
If you use several AI coding agents (OpenAI Codex, Claude Code, WorkBuddy, …), you end up with
|
|
34
|
+
skill libraries scattered across different directories, in different layouts, some copied, some
|
|
35
|
+
stale, some requiring dependencies you never installed. `skillsync` turns that mess into one
|
|
36
|
+
honest inventory — automatically.
|
|
37
|
+
|
|
38
|
+
Zero dependencies. Pure Python ≥ 3.11 stdlib.
|
|
39
|
+
|
|
40
|
+
## What it does
|
|
41
|
+
|
|
42
|
+
```
|
|
43
|
+
┌──────────────┐ ┌──────────────┐ ┌────────────────┐
|
|
44
|
+
│ ~/.codex/ │ │ marketplace │ │ ~/.claude/ │ … any number of
|
|
45
|
+
│ skills/ │ │ plugin cache │ │ skills/ │ source roots
|
|
46
|
+
└──────┬───────┘ └──────┬───────┘ └───────┬────────┘
|
|
47
|
+
└──────────────┬───┴───────────────────┘
|
|
48
|
+
▼
|
|
49
|
+
┌───────────────┐ classify every skill:
|
|
50
|
+
│ scan + parse │ A portable · B missing deps
|
|
51
|
+
│ frontmatter │ C rewrite needed · D platform-private
|
|
52
|
+
└───────┬───────┘
|
|
53
|
+
▼
|
|
54
|
+
┌───────────────┐ diff against target:
|
|
55
|
+
│ INDEX.md │ identical · drifted · missing
|
|
56
|
+
│ inventory.json│
|
|
57
|
+
└───────┬───────┘
|
|
58
|
+
▼
|
|
59
|
+
┌───────────────┐ optional, safe copy:
|
|
60
|
+
│ skillsync sync│ dry-run first, backups, never deletes,
|
|
61
|
+
└───────────────┘ skips .venv/.env/node_modules
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### The A/B/C/D migration taxonomy
|
|
65
|
+
|
|
66
|
+
| Category | Meaning | Action |
|
|
67
|
+
|---|---|---|
|
|
68
|
+
| **A** | Portable — no platform-private references, every referenced command exists | copy & use |
|
|
69
|
+
| **B** | Portable but missing external deps (a CLI, an MCP server) | install deps, then copy |
|
|
70
|
+
| **C** | References another agent's conventions (`AGENTS.md`, `image_gen`, …) | rewrite for your target |
|
|
71
|
+
| **D** | Bound to the source platform's private runtime | don't migrate |
|
|
72
|
+
|
|
73
|
+
Classification is heuristic, conservative, and **every decision ships a reason** —
|
|
74
|
+
the index shows *why* a skill landed in each bucket, and *which* dependencies are missing
|
|
75
|
+
(probed live with `shutil.which` / your `[deps]` table).
|
|
76
|
+
|
|
77
|
+
## Install
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
pipx install agent-skill-sync # recommended: isolated CLI install
|
|
81
|
+
pip install agent-skill-sync # or into your environment
|
|
82
|
+
|
|
83
|
+
# from source, without installing:
|
|
84
|
+
git clone https://github.com/kina-cmd/agent-skill-sync && cd agent-skill-sync
|
|
85
|
+
python -m skillsync.cli --help
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
## Usage
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
# What do I have, and in what state?
|
|
92
|
+
skillsync status
|
|
93
|
+
|
|
94
|
+
# One line per skill: category, sync state, source, missing deps
|
|
95
|
+
skillsync scan
|
|
96
|
+
skillsync scan --category B # only the ones needing deps
|
|
97
|
+
skillsync scan --json # machine-readable inventory
|
|
98
|
+
|
|
99
|
+
# Generate a full index (INDEX.md + inventory.json) you can commit
|
|
100
|
+
# or paste into a "tool reuse" skill for your agent to read
|
|
101
|
+
skillsync index --out ./output --lang zh
|
|
102
|
+
|
|
103
|
+
# Sync portable skills into the target root — plan first, always
|
|
104
|
+
skillsync sync --dry-run
|
|
105
|
+
skillsync sync --categories A
|
|
106
|
+
skillsync sync --categories A,B --force # update drifted copies (backs them up)
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
### Sync safety rules
|
|
110
|
+
|
|
111
|
+
* Never overwrites without `--force`; a forced update first moves the old copy to
|
|
112
|
+
`<target>/.skillsync-backup/` — nothing is ever deleted.
|
|
113
|
+
* `.venv/`, `.env`, `node_modules/`, `__pycache__/` are always excluded from copies,
|
|
114
|
+
so secrets and 500 MB virtualenvs never travel silently.
|
|
115
|
+
* `--dry-run` prints the exact plan and touches nothing.
|
|
116
|
+
|
|
117
|
+
## Configuration
|
|
118
|
+
|
|
119
|
+
By default, `skillsync` auto-discovers the well-known roots on your machine
|
|
120
|
+
(`~/.codex/skills`, `~/.codex/plugins/cache`, `~/.claude/skills` → target `~/.workbuddy/skills`).
|
|
121
|
+
|
|
122
|
+
Override or extend with `skillsync.toml` (looked up in `./` then `$XDG_CONFIG_HOME/skillsync/`):
|
|
123
|
+
|
|
124
|
+
```toml
|
|
125
|
+
[target]
|
|
126
|
+
label = "workbuddy"
|
|
127
|
+
path = "~/.workbuddy/skills"
|
|
128
|
+
|
|
129
|
+
[[sources]]
|
|
130
|
+
label = "codex"
|
|
131
|
+
path = "~/.codex/skills"
|
|
132
|
+
|
|
133
|
+
[[sources]]
|
|
134
|
+
label = "codex-marketplace"
|
|
135
|
+
path = "~/.codex/plugins/cache"
|
|
136
|
+
glob = "**/skills/*/SKILL.md"
|
|
137
|
+
|
|
138
|
+
[[sources]]
|
|
139
|
+
label = "codex-system"
|
|
140
|
+
path = "~/.codex/skills/.system"
|
|
141
|
+
system = true # platform-private → always category D
|
|
142
|
+
|
|
143
|
+
[deps]
|
|
144
|
+
# Teach the classifier that a dep is satisfied even if not on PATH:
|
|
145
|
+
voicebox = { kind = "path", value = "~/App/Voicebox/voicebox.exe" }
|
|
146
|
+
ffmpeg = "ffmpeg" # shorthand: check PATH
|
|
147
|
+
notion = { kind = "env", value = "NOTION_TOKEN" } # check env var
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
See [`skillsync.example.toml`](skillsync.example.toml) for a complete example.
|
|
151
|
+
|
|
152
|
+
## Typical workflow: keeping an index skill fresh
|
|
153
|
+
|
|
154
|
+
Many people maintain a hand-written "local tool reuse" index for their agent.
|
|
155
|
+
It rots the moment a skill is added upstream. Instead:
|
|
156
|
+
|
|
157
|
+
```bash
|
|
158
|
+
skillsync index --out ~/.workbuddy/skills/local-tool-reuse/generated --lang zh
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
…on a schedule or a git hook, and let the agent read a generated file that is
|
|
162
|
+
always true. `inventory.json` is stable, machine-readable output for further tooling.
|
|
163
|
+
|
|
164
|
+
## Development
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
python -m unittest discover tests -v
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
## Design notes
|
|
171
|
+
|
|
172
|
+
* **No PyYAML.** The frontmatter parser implements exactly the YAML subset skill
|
|
173
|
+
files use (scalars, folded/literal blocks, inline and block lists), and fails soft —
|
|
174
|
+
unparsable lines become warnings, never crashes.
|
|
175
|
+
* **No network.** Everything is local filesystem inspection.
|
|
176
|
+
* **Qualified names.** Marketplace plugin caches nest skills as
|
|
177
|
+
`<plugin>/<version>/skills/<name>/`; these are reported as `plugin:name` so
|
|
178
|
+
collisions are visible.
|
|
179
|
+
|
|
180
|
+
## License
|
|
181
|
+
|
|
182
|
+
MIT © 2026 kina-cmd
|
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
# agent-skill-sync
|
|
2
|
+
|
|
3
|
+
[](https://github.com/kina-cmd/agent-skill-sync/actions/workflows/ci.yml)
|
|
4
|
+
[](https://pypi.org/project/agent-skill-sync/)
|
|
5
|
+
[](https://pypi.org/project/agent-skill-sync/)
|
|
6
|
+
[](LICENSE)
|
|
7
|
+
|
|
8
|
+
**`skillsync`** — scan, classify and sync AI-agent skills (`SKILL.md` files) across toolchains.
|
|
9
|
+
|
|
10
|
+
If you use several AI coding agents (OpenAI Codex, Claude Code, WorkBuddy, …), you end up with
|
|
11
|
+
skill libraries scattered across different directories, in different layouts, some copied, some
|
|
12
|
+
stale, some requiring dependencies you never installed. `skillsync` turns that mess into one
|
|
13
|
+
honest inventory — automatically.
|
|
14
|
+
|
|
15
|
+
Zero dependencies. Pure Python ≥ 3.11 stdlib.
|
|
16
|
+
|
|
17
|
+
## What it does
|
|
18
|
+
|
|
19
|
+
```
|
|
20
|
+
┌──────────────┐ ┌──────────────┐ ┌────────────────┐
|
|
21
|
+
│ ~/.codex/ │ │ marketplace │ │ ~/.claude/ │ … any number of
|
|
22
|
+
│ skills/ │ │ plugin cache │ │ skills/ │ source roots
|
|
23
|
+
└──────┬───────┘ └──────┬───────┘ └───────┬────────┘
|
|
24
|
+
└──────────────┬───┴───────────────────┘
|
|
25
|
+
▼
|
|
26
|
+
┌───────────────┐ classify every skill:
|
|
27
|
+
│ scan + parse │ A portable · B missing deps
|
|
28
|
+
│ frontmatter │ C rewrite needed · D platform-private
|
|
29
|
+
└───────┬───────┘
|
|
30
|
+
▼
|
|
31
|
+
┌───────────────┐ diff against target:
|
|
32
|
+
│ INDEX.md │ identical · drifted · missing
|
|
33
|
+
│ inventory.json│
|
|
34
|
+
└───────┬───────┘
|
|
35
|
+
▼
|
|
36
|
+
┌───────────────┐ optional, safe copy:
|
|
37
|
+
│ skillsync sync│ dry-run first, backups, never deletes,
|
|
38
|
+
└───────────────┘ skips .venv/.env/node_modules
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
### The A/B/C/D migration taxonomy
|
|
42
|
+
|
|
43
|
+
| Category | Meaning | Action |
|
|
44
|
+
|---|---|---|
|
|
45
|
+
| **A** | Portable — no platform-private references, every referenced command exists | copy & use |
|
|
46
|
+
| **B** | Portable but missing external deps (a CLI, an MCP server) | install deps, then copy |
|
|
47
|
+
| **C** | References another agent's conventions (`AGENTS.md`, `image_gen`, …) | rewrite for your target |
|
|
48
|
+
| **D** | Bound to the source platform's private runtime | don't migrate |
|
|
49
|
+
|
|
50
|
+
Classification is heuristic, conservative, and **every decision ships a reason** —
|
|
51
|
+
the index shows *why* a skill landed in each bucket, and *which* dependencies are missing
|
|
52
|
+
(probed live with `shutil.which` / your `[deps]` table).
|
|
53
|
+
|
|
54
|
+
## Install
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
pipx install agent-skill-sync # recommended: isolated CLI install
|
|
58
|
+
pip install agent-skill-sync # or into your environment
|
|
59
|
+
|
|
60
|
+
# from source, without installing:
|
|
61
|
+
git clone https://github.com/kina-cmd/agent-skill-sync && cd agent-skill-sync
|
|
62
|
+
python -m skillsync.cli --help
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Usage
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
# What do I have, and in what state?
|
|
69
|
+
skillsync status
|
|
70
|
+
|
|
71
|
+
# One line per skill: category, sync state, source, missing deps
|
|
72
|
+
skillsync scan
|
|
73
|
+
skillsync scan --category B # only the ones needing deps
|
|
74
|
+
skillsync scan --json # machine-readable inventory
|
|
75
|
+
|
|
76
|
+
# Generate a full index (INDEX.md + inventory.json) you can commit
|
|
77
|
+
# or paste into a "tool reuse" skill for your agent to read
|
|
78
|
+
skillsync index --out ./output --lang zh
|
|
79
|
+
|
|
80
|
+
# Sync portable skills into the target root — plan first, always
|
|
81
|
+
skillsync sync --dry-run
|
|
82
|
+
skillsync sync --categories A
|
|
83
|
+
skillsync sync --categories A,B --force # update drifted copies (backs them up)
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
### Sync safety rules
|
|
87
|
+
|
|
88
|
+
* Never overwrites without `--force`; a forced update first moves the old copy to
|
|
89
|
+
`<target>/.skillsync-backup/` — nothing is ever deleted.
|
|
90
|
+
* `.venv/`, `.env`, `node_modules/`, `__pycache__/` are always excluded from copies,
|
|
91
|
+
so secrets and 500 MB virtualenvs never travel silently.
|
|
92
|
+
* `--dry-run` prints the exact plan and touches nothing.
|
|
93
|
+
|
|
94
|
+
## Configuration
|
|
95
|
+
|
|
96
|
+
By default, `skillsync` auto-discovers the well-known roots on your machine
|
|
97
|
+
(`~/.codex/skills`, `~/.codex/plugins/cache`, `~/.claude/skills` → target `~/.workbuddy/skills`).
|
|
98
|
+
|
|
99
|
+
Override or extend with `skillsync.toml` (looked up in `./` then `$XDG_CONFIG_HOME/skillsync/`):
|
|
100
|
+
|
|
101
|
+
```toml
|
|
102
|
+
[target]
|
|
103
|
+
label = "workbuddy"
|
|
104
|
+
path = "~/.workbuddy/skills"
|
|
105
|
+
|
|
106
|
+
[[sources]]
|
|
107
|
+
label = "codex"
|
|
108
|
+
path = "~/.codex/skills"
|
|
109
|
+
|
|
110
|
+
[[sources]]
|
|
111
|
+
label = "codex-marketplace"
|
|
112
|
+
path = "~/.codex/plugins/cache"
|
|
113
|
+
glob = "**/skills/*/SKILL.md"
|
|
114
|
+
|
|
115
|
+
[[sources]]
|
|
116
|
+
label = "codex-system"
|
|
117
|
+
path = "~/.codex/skills/.system"
|
|
118
|
+
system = true # platform-private → always category D
|
|
119
|
+
|
|
120
|
+
[deps]
|
|
121
|
+
# Teach the classifier that a dep is satisfied even if not on PATH:
|
|
122
|
+
voicebox = { kind = "path", value = "~/App/Voicebox/voicebox.exe" }
|
|
123
|
+
ffmpeg = "ffmpeg" # shorthand: check PATH
|
|
124
|
+
notion = { kind = "env", value = "NOTION_TOKEN" } # check env var
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
See [`skillsync.example.toml`](skillsync.example.toml) for a complete example.
|
|
128
|
+
|
|
129
|
+
## Typical workflow: keeping an index skill fresh
|
|
130
|
+
|
|
131
|
+
Many people maintain a hand-written "local tool reuse" index for their agent.
|
|
132
|
+
It rots the moment a skill is added upstream. Instead:
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
skillsync index --out ~/.workbuddy/skills/local-tool-reuse/generated --lang zh
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
…on a schedule or a git hook, and let the agent read a generated file that is
|
|
139
|
+
always true. `inventory.json` is stable, machine-readable output for further tooling.
|
|
140
|
+
|
|
141
|
+
## Development
|
|
142
|
+
|
|
143
|
+
```bash
|
|
144
|
+
python -m unittest discover tests -v
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
## Design notes
|
|
148
|
+
|
|
149
|
+
* **No PyYAML.** The frontmatter parser implements exactly the YAML subset skill
|
|
150
|
+
files use (scalars, folded/literal blocks, inline and block lists), and fails soft —
|
|
151
|
+
unparsable lines become warnings, never crashes.
|
|
152
|
+
* **No network.** Everything is local filesystem inspection.
|
|
153
|
+
* **Qualified names.** Marketplace plugin caches nest skills as
|
|
154
|
+
`<plugin>/<version>/skills/<name>/`; these are reported as `plugin:name` so
|
|
155
|
+
collisions are visible.
|
|
156
|
+
|
|
157
|
+
## License
|
|
158
|
+
|
|
159
|
+
MIT © 2026 kina-cmd
|
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: agent-skill-sync
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Scan, classify and sync AI-agent skills (SKILL.md) across toolchains like OpenAI Codex, Claude Code and WorkBuddy.
|
|
5
|
+
License: MIT
|
|
6
|
+
Project-URL: Homepage, https://github.com/kina-cmd/agent-skill-sync
|
|
7
|
+
Project-URL: Issues, https://github.com/kina-cmd/agent-skill-sync/issues
|
|
8
|
+
Keywords: ai,agent,skills,codex,claude,workbuddy,migration,inventory
|
|
9
|
+
Classifier: Development Status :: 3 - Alpha
|
|
10
|
+
Classifier: Environment :: Console
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
17
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
18
|
+
Classifier: Topic :: Utilities
|
|
19
|
+
Requires-Python: >=3.11
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
License-File: LICENSE
|
|
22
|
+
Dynamic: license-file
|
|
23
|
+
|
|
24
|
+
# agent-skill-sync
|
|
25
|
+
|
|
26
|
+
[](https://github.com/kina-cmd/agent-skill-sync/actions/workflows/ci.yml)
|
|
27
|
+
[](https://pypi.org/project/agent-skill-sync/)
|
|
28
|
+
[](https://pypi.org/project/agent-skill-sync/)
|
|
29
|
+
[](LICENSE)
|
|
30
|
+
|
|
31
|
+
**`skillsync`** — scan, classify and sync AI-agent skills (`SKILL.md` files) across toolchains.
|
|
32
|
+
|
|
33
|
+
If you use several AI coding agents (OpenAI Codex, Claude Code, WorkBuddy, …), you end up with
|
|
34
|
+
skill libraries scattered across different directories, in different layouts, some copied, some
|
|
35
|
+
stale, some requiring dependencies you never installed. `skillsync` turns that mess into one
|
|
36
|
+
honest inventory — automatically.
|
|
37
|
+
|
|
38
|
+
Zero dependencies. Pure Python ≥ 3.11 stdlib.
|
|
39
|
+
|
|
40
|
+
## What it does
|
|
41
|
+
|
|
42
|
+
```
|
|
43
|
+
┌──────────────┐ ┌──────────────┐ ┌────────────────┐
|
|
44
|
+
│ ~/.codex/ │ │ marketplace │ │ ~/.claude/ │ … any number of
|
|
45
|
+
│ skills/ │ │ plugin cache │ │ skills/ │ source roots
|
|
46
|
+
└──────┬───────┘ └──────┬───────┘ └───────┬────────┘
|
|
47
|
+
└──────────────┬───┴───────────────────┘
|
|
48
|
+
▼
|
|
49
|
+
┌───────────────┐ classify every skill:
|
|
50
|
+
│ scan + parse │ A portable · B missing deps
|
|
51
|
+
│ frontmatter │ C rewrite needed · D platform-private
|
|
52
|
+
└───────┬───────┘
|
|
53
|
+
▼
|
|
54
|
+
┌───────────────┐ diff against target:
|
|
55
|
+
│ INDEX.md │ identical · drifted · missing
|
|
56
|
+
│ inventory.json│
|
|
57
|
+
└───────┬───────┘
|
|
58
|
+
▼
|
|
59
|
+
┌───────────────┐ optional, safe copy:
|
|
60
|
+
│ skillsync sync│ dry-run first, backups, never deletes,
|
|
61
|
+
└───────────────┘ skips .venv/.env/node_modules
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### The A/B/C/D migration taxonomy
|
|
65
|
+
|
|
66
|
+
| Category | Meaning | Action |
|
|
67
|
+
|---|---|---|
|
|
68
|
+
| **A** | Portable — no platform-private references, every referenced command exists | copy & use |
|
|
69
|
+
| **B** | Portable but missing external deps (a CLI, an MCP server) | install deps, then copy |
|
|
70
|
+
| **C** | References another agent's conventions (`AGENTS.md`, `image_gen`, …) | rewrite for your target |
|
|
71
|
+
| **D** | Bound to the source platform's private runtime | don't migrate |
|
|
72
|
+
|
|
73
|
+
Classification is heuristic, conservative, and **every decision ships a reason** —
|
|
74
|
+
the index shows *why* a skill landed in each bucket, and *which* dependencies are missing
|
|
75
|
+
(probed live with `shutil.which` / your `[deps]` table).
|
|
76
|
+
|
|
77
|
+
## Install
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
pipx install agent-skill-sync # recommended: isolated CLI install
|
|
81
|
+
pip install agent-skill-sync # or into your environment
|
|
82
|
+
|
|
83
|
+
# from source, without installing:
|
|
84
|
+
git clone https://github.com/kina-cmd/agent-skill-sync && cd agent-skill-sync
|
|
85
|
+
python -m skillsync.cli --help
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
## Usage
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
# What do I have, and in what state?
|
|
92
|
+
skillsync status
|
|
93
|
+
|
|
94
|
+
# One line per skill: category, sync state, source, missing deps
|
|
95
|
+
skillsync scan
|
|
96
|
+
skillsync scan --category B # only the ones needing deps
|
|
97
|
+
skillsync scan --json # machine-readable inventory
|
|
98
|
+
|
|
99
|
+
# Generate a full index (INDEX.md + inventory.json) you can commit
|
|
100
|
+
# or paste into a "tool reuse" skill for your agent to read
|
|
101
|
+
skillsync index --out ./output --lang zh
|
|
102
|
+
|
|
103
|
+
# Sync portable skills into the target root — plan first, always
|
|
104
|
+
skillsync sync --dry-run
|
|
105
|
+
skillsync sync --categories A
|
|
106
|
+
skillsync sync --categories A,B --force # update drifted copies (backs them up)
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
### Sync safety rules
|
|
110
|
+
|
|
111
|
+
* Never overwrites without `--force`; a forced update first moves the old copy to
|
|
112
|
+
`<target>/.skillsync-backup/` — nothing is ever deleted.
|
|
113
|
+
* `.venv/`, `.env`, `node_modules/`, `__pycache__/` are always excluded from copies,
|
|
114
|
+
so secrets and 500 MB virtualenvs never travel silently.
|
|
115
|
+
* `--dry-run` prints the exact plan and touches nothing.
|
|
116
|
+
|
|
117
|
+
## Configuration
|
|
118
|
+
|
|
119
|
+
By default, `skillsync` auto-discovers the well-known roots on your machine
|
|
120
|
+
(`~/.codex/skills`, `~/.codex/plugins/cache`, `~/.claude/skills` → target `~/.workbuddy/skills`).
|
|
121
|
+
|
|
122
|
+
Override or extend with `skillsync.toml` (looked up in `./` then `$XDG_CONFIG_HOME/skillsync/`):
|
|
123
|
+
|
|
124
|
+
```toml
|
|
125
|
+
[target]
|
|
126
|
+
label = "workbuddy"
|
|
127
|
+
path = "~/.workbuddy/skills"
|
|
128
|
+
|
|
129
|
+
[[sources]]
|
|
130
|
+
label = "codex"
|
|
131
|
+
path = "~/.codex/skills"
|
|
132
|
+
|
|
133
|
+
[[sources]]
|
|
134
|
+
label = "codex-marketplace"
|
|
135
|
+
path = "~/.codex/plugins/cache"
|
|
136
|
+
glob = "**/skills/*/SKILL.md"
|
|
137
|
+
|
|
138
|
+
[[sources]]
|
|
139
|
+
label = "codex-system"
|
|
140
|
+
path = "~/.codex/skills/.system"
|
|
141
|
+
system = true # platform-private → always category D
|
|
142
|
+
|
|
143
|
+
[deps]
|
|
144
|
+
# Teach the classifier that a dep is satisfied even if not on PATH:
|
|
145
|
+
voicebox = { kind = "path", value = "~/App/Voicebox/voicebox.exe" }
|
|
146
|
+
ffmpeg = "ffmpeg" # shorthand: check PATH
|
|
147
|
+
notion = { kind = "env", value = "NOTION_TOKEN" } # check env var
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
See [`skillsync.example.toml`](skillsync.example.toml) for a complete example.
|
|
151
|
+
|
|
152
|
+
## Typical workflow: keeping an index skill fresh
|
|
153
|
+
|
|
154
|
+
Many people maintain a hand-written "local tool reuse" index for their agent.
|
|
155
|
+
It rots the moment a skill is added upstream. Instead:
|
|
156
|
+
|
|
157
|
+
```bash
|
|
158
|
+
skillsync index --out ~/.workbuddy/skills/local-tool-reuse/generated --lang zh
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
…on a schedule or a git hook, and let the agent read a generated file that is
|
|
162
|
+
always true. `inventory.json` is stable, machine-readable output for further tooling.
|
|
163
|
+
|
|
164
|
+
## Development
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
python -m unittest discover tests -v
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
## Design notes
|
|
171
|
+
|
|
172
|
+
* **No PyYAML.** The frontmatter parser implements exactly the YAML subset skill
|
|
173
|
+
files use (scalars, folded/literal blocks, inline and block lists), and fails soft —
|
|
174
|
+
unparsable lines become warnings, never crashes.
|
|
175
|
+
* **No network.** Everything is local filesystem inspection.
|
|
176
|
+
* **Qualified names.** Marketplace plugin caches nest skills as
|
|
177
|
+
`<plugin>/<version>/skills/<name>/`; these are reported as `plugin:name` so
|
|
178
|
+
collisions are visible.
|
|
179
|
+
|
|
180
|
+
## License
|
|
181
|
+
|
|
182
|
+
MIT © 2026 kina-cmd
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
LICENSE
|
|
2
|
+
README.md
|
|
3
|
+
pyproject.toml
|
|
4
|
+
agent_skill_sync.egg-info/PKG-INFO
|
|
5
|
+
agent_skill_sync.egg-info/SOURCES.txt
|
|
6
|
+
agent_skill_sync.egg-info/dependency_links.txt
|
|
7
|
+
agent_skill_sync.egg-info/entry_points.txt
|
|
8
|
+
agent_skill_sync.egg-info/top_level.txt
|
|
9
|
+
skillsync/__init__.py
|
|
10
|
+
skillsync/classifier.py
|
|
11
|
+
skillsync/cli.py
|
|
12
|
+
skillsync/config.py
|
|
13
|
+
skillsync/differ.py
|
|
14
|
+
skillsync/frontmatter.py
|
|
15
|
+
skillsync/model.py
|
|
16
|
+
skillsync/report.py
|
|
17
|
+
skillsync/resolve.py
|
|
18
|
+
skillsync/scanner.py
|
|
19
|
+
skillsync/sync.py
|
|
20
|
+
tests/test_skillsync.py
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
skillsync
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=68"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "agent-skill-sync"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Scan, classify and sync AI-agent skills (SKILL.md) across toolchains like OpenAI Codex, Claude Code and WorkBuddy."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = { text = "MIT" }
|
|
11
|
+
requires-python = ">=3.11"
|
|
12
|
+
keywords = ["ai", "agent", "skills", "codex", "claude", "workbuddy", "migration", "inventory"]
|
|
13
|
+
classifiers = [
|
|
14
|
+
"Development Status :: 3 - Alpha",
|
|
15
|
+
"Environment :: Console",
|
|
16
|
+
"Intended Audience :: Developers",
|
|
17
|
+
"License :: OSI Approved :: MIT License",
|
|
18
|
+
"Programming Language :: Python :: 3",
|
|
19
|
+
"Programming Language :: Python :: 3.11",
|
|
20
|
+
"Programming Language :: Python :: 3.12",
|
|
21
|
+
"Programming Language :: Python :: 3.13",
|
|
22
|
+
"Topic :: Software Development :: Quality Assurance",
|
|
23
|
+
"Topic :: Utilities",
|
|
24
|
+
]
|
|
25
|
+
dependencies = []
|
|
26
|
+
|
|
27
|
+
[project.scripts]
|
|
28
|
+
skillsync = "skillsync.cli:main"
|
|
29
|
+
|
|
30
|
+
[project.urls]
|
|
31
|
+
Homepage = "https://github.com/kina-cmd/agent-skill-sync"
|
|
32
|
+
Issues = "https://github.com/kina-cmd/agent-skill-sync/issues"
|
|
33
|
+
|
|
34
|
+
[tool.setuptools.packages.find]
|
|
35
|
+
include = ["skillsync*"]
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
"""skillsync — scan, classify and sync agent skills between toolchains.
|
|
2
|
+
|
|
3
|
+
A dependency-free toolkit for people who accumulate AI-agent "skills"
|
|
4
|
+
(SKILL.md files) across several CLIs — OpenAI Codex, Claude Code, WorkBuddy,
|
|
5
|
+
etc. — and want one honest inventory: what exists, where it lives, whether it
|
|
6
|
+
is runnable, and what it would take to migrate it.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
__version__ = "0.1.0"
|
|
10
|
+
|
|
11
|
+
__all__ = ["__version__"]
|