Skip to content
Back to search

ai-extension-manager

SkillWorks with Claude CodeGitHub

Sync AI agent skills, rules and MCP configs across Claude Code, Codex, Gemini CLI, Cursor, VS Code Copilot and DSH from one local library, with hash-based conflict detection, backups and security review. Use when the user wants to install a skill or plugin from GitHub, keep skills in sync between AI tools, import what a tool already has, compare or repair drifted copies, resolve a two-way sync conflict, or back up / restore AI resources. Triggers: "把这个 GitHub 技能装到 Claude Code 和 Codex", "把六个工具新增的 Skill 导入中央库", "同步/备份/恢复 AI 扩展". Do not use it for editing application code that merely mentions MCP or skills.

Safety scan

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

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jack91124--ai-extension-manager/badge.svg)](/listings/jack91124--ai-extension-manager)

HTML

<a href="/listings/jack91124--ai-extension-manager"><img src="/api/listings/jack91124--ai-extension-manager/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.

Requires **Python 3.9+**. No third-party packages, on Windows, macOS or Linux.

Install without cloning (needs `git`; pin the tag for a reproducible install):

python -m pip install --user "git+https://github.com/Jack91124/ai-extension-manager.git@v1.0.3"
aem init && aem doctor

Prefer an isolated CLI? Use `pipx install "git+https://github.com/Jack91124/ai-extension-manager.git@v1.0.3"`, or download the wheel from the [latest release](https://github.com/Jack91124/ai-extension-manager/releases/latest) and `pip install` it.

Or clone the repository:

git clone https://github.com/Jack91124/ai-extension-manager.git
cd ai-extension-manager
python -m pip install .
aem init          # create ~/.ai-extension-manager
aem doctor        # check Python, paths, registry, locks and installed tools
aem scan          # detect the six tools and their skill folders

No install needed — every command also runs as `python scripts/aem.py <command>`.

Already use the [`skills`](https://github.com/vercel-labs/skills) CLI? Install it as an agent skill (Node 22.20+), which also lists it on [skills.sh](https://www.skills.sh/jack91124/ai-extension-manager):

npx skills add Jack91124/ai-extension-manager

The repository root is a valid skill, so the CLI installs the whole toolkit (docs, scripts, evals) into `.claude/skills/ai-extension-manager` or `.agents/skills/ai-extension-manager`.

A real `aem doctor` run on a Windows machine where three of the six tools are installed:

$ aem doctor
[ok]   python    3.14.4 (requires 3.9+)
[ok]   library   C:\Users\you\.ai-extension-manager is writable
[ok]   registry  0 resources
[ok]   schema    schema 1
[ok]   payloads  all payload directories present
[ok]   lock      no library lock
[ok]   agents    3/6 tools installed; absent: gemini, cursor
[ok]   disk      132.4GB free
[ok]   backups   0 snapshots, 0B
[ok]   conflicts 0 unresolved conflict(s)
result: healthy

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.

SKILL.md · Manifest · 325 lines
  1. ---
  2. name: ai-extension-manager
  3. description: >-
  4. Sync AI agent skills, rules and MCP configs across Claude Code, Codex, Gemini CLI, Cursor, VS Code Copilot
  5. and DSH from one local library, with hash-based conflict detection, backups and security review. Use when
  6. the user wants to install a skill or plugin from GitHub, keep skills in sync between AI tools, import what
  7. a tool already has, compare or repair drifted copies, resolve a two-way sync conflict, or back up / restore
  8. AI resources. Triggers: "把这个 GitHub 技能装到 Claude Code 和 Codex", "把六个工具新增的 Skill 导入中央库",
  9. "同步/备份/恢复 AI 扩展". Do not use it for editing application code that merely mentions MCP or skills.
  10. license: MIT
  11. compatibility: Python 3.9+ (standard library only), git for remote repositories, Windows/macOS/Linux. Optional DSH Plugin is NOT included; scripts are the execution layer until that plugin exists.
  12. allowed-tools: Read Write Edit Bash Glob Grep
  13. metadata:
  14. display_name: AI Extension Manager
  15. display_name_zh: AI 扩展资源管理助手
  16. version: 1.0.4
  17. category: developer-tools
  18. phase: v1.0 (CLI + Agent Skill; DSH Plugin specified, not built)
  19. ---
  20. # AI Extension Manager
  21. One central library, six AI tools, two-way synchronization. This skill is the
  22. **decision layer**: it classifies a resource, checks compatibility and safety,
  23. plans the change, executes it through the bundled Python tools (or the DSH
  24. Plugin once one exists), verifies the result and reports it.
  25. The bundled scripts are the only execution layer that exists today. There is no
  26. graphical DSH Plugin yet. Never claim that a plugin UI, a plugin tool, or a
  27. native API of another AI tool is available unless the environment scan proves it.
  28. ## Install and run
  29. The stable entry point is `aem`; the seven Python scripts remain the implementation.
  30. ```bash
  31. python -m pip install . # from a source checkout; installs the `aem` command
  32. aem init # create ~/.ai-extension-manager
  33. aem doctor # check Python, paths, registry, locks and tools
  34. aem status # resource x agent sync state
  35. ```
  36. Without installing, every command also works as `python scripts/aem.py <command>`.
  37. | Command | Purpose |
  38. |---|---|
  39. | `aem scan` | detect the six tools and their skill directories |
  40. | `aem detect --path P` | classify P as skill / plugin / MCP / rules |
  41. | `aem import --source P` | import into the central library |
  42. | `aem sync --direction distribute --agent claude --agent codex --resource NAME` | distribute |
  43. | `aem adopt` / `aem distribute` | one-word shortcuts for the two sync directions |
  44. | `aem verify --all` | verify installed copies |
  45. | `aem status` | one table of every resource x agent pair |
  46. | `aem doctor` | diagnose setup problems with fixes |
  47. All commands accept `--home`, `--workspace` and `--json`; see `references/cli-reference.md`.
  48. ## Non-negotiable rules
  49. 1. **Detect before you touch.** Run `scripts/scan_agents.py` first. Never guess a tool's
  50. directory, version or capability; the registry marks every path as
  51. local / official / partial / unverified.
  52. 2. **No silent overwrite.** Any existing file or resource that differs from the
  53. incoming content is a conflict. Conflicts require an explicit resolution
  54. (keep library / keep target / manual merge / save as new version). The scripts
  55. exit 2 and store evidence instead of overwriting.
  56. 3. **Back up before replacing.** The engine snapshots the target and the library
  57. version before every write. Backups live under `<home>/backups/`.
  58. 4. **Review before installing code.** Run the built-in safety scan, read the
  59. scripts that will ship, and get explicit user confirmation for high/medium
  60. risk resources or for anything that installs packages, runs shell commands,
  61. or ships binaries.
  62. 5. **Secrets never enter the library.** Credentials found in skills are refused;
  63. credentials in MCP configs are replaced with `${ENV_VAR}` placeholders and the
  64. user must export the variable. Never echo a secret into a report.
  65. 6. **Honest capability reporting.** If a tool is absent, a plugin mechanism is
  66. unverified, or a distribution path is not implemented, say so and stop. A
  67. partial result reported accurately is better than a fake success.
  68. ## Establish context (run first, every session)
  69. ```bash
  70. python scripts/scan_agents.py --json
  71. python scripts/scan_agents.py --workspace <project> --json # adds project-scope dirs
  72. ```
  73. Both scan commands are read-only: they never create the central library. The first
  74. mutating command creates it. If the default location is not writable (sandboxed
  75. hosts, read-only home), pass `--home <writable-dir>` and tell the user which root you used.
  76. Use the JSON: tool status (installed / config-only / absent), CLI version, skill
  77. directories and their counts, plugin system, MCP and rules capability, plus
  78. `verification` flags. Record the central library root: it defaults to
  79. `$AEM_HOME` or `~/.ai-extension-manager`. Pass `--home` when the user wants another location.
  80. If the request names a specific tool that is `absent`, say so immediately and offer
  81. one of: install the resource somewhere present, prepare a portable copy, or stop.
  82. Do not create directories inside a tool that is not installed.
  83. ## Pick the workflow
  84. | User intent | Workflow | Primary commands |
  85. |---|---|---|
  86. | "install this GitHub skill / plugin" | A. Install from source | `detect_resources.py --url` then `import_resource.py` |
  87. | "what's new in my AI tools?" | B. Scan and import | `sync_resources.py --direction import` |
  88. | "sync this skill to Codex and Claude" | C. Distribute | `sync_resources.py --direction distribute --agent ...` |
  89. | "make all tools match the library" | D. Two-way sync | `sync_resources.py --direction both` |
  90. | "these copies disagree" | E. Conflict review | `compare_resources.py` + manual decision |
  91. | "is the install still correct?" | F. Verify / repair | `verify_sync.py` then re-distribute |
  92. | "roll back / restore" | G. Backups | `backup_restore.py` |
  93. | "install this plugin for me" | H. Plugin planning | plugin action is a plan + command, see below |
  94. | "what do I have?" | I. Inventory report | `detect_resources.py --all-agents` + registry |
  95. Detailed contracts live in `references/`; read only what the task needs:
  96. - `architecture.md` - layers, Skill/Plugin boundary, operation contract
  97. - `resource-types.md` - classification signals, record schema, payload layout
  98. - `agent-compatibility.md` - verified paths and capabilities per tool
  99. - `synchronization-engine.md` - state machine, modes, journal, idempotency
  100. - `conflict-resolution.md` - detection math and resolution procedures
  101. - `security-policy.md` - scanner rules, confirmation gates, secret handling
  102. - `installation-methods.md` - per-tool install/uninstall mechanics
  103. - `dsh-plugin-spec.md` - specification for the future dashboard plugin
  104. ## Workflow A - install from a GitHub URL or local path
  105. 1. Classify the source **before** downloading when possible:
  106. `python scripts/detect_resources.py --url <url> --json`
  107. The result says whether the URL is a repository, which host it is, and the
  108. exact import command. Recognised types: `skill`, `plugin`, `mcp`, `rules`.
  109. 2. Before any remote import, the tool audits git `url.*.insteadOf` rewrites. A rule
  110. that sends github.com clones to a third-party mirror is refused with
  111. `git-rewrite-detected` (exit 1): show the rule and ask; only pass `--allow-mirror`
  112. if the user trusts that mirror. A URL dry run still clones into `staging/`
  113. (classification needs the files) and cleans up afterwards; local paths have no
  114. such side effect.
  115. 3. For a remote repo, import with conflict policy and a dry run first:
  116. `python scripts/import_resource.py --source <url> --dry-run --json`
  117. Then run without `--dry-run`. The clone is shallow and goes to `staging/`.
  118. 4. Read the JSON result. `needs-confirmation` means the security scanner found
  119. shell piping, recursive deletes, binary payloads or other risky patterns:
  120. summarize the findings, show the file and line, and ask before re-running
  121. with `--allow-risk`. `secret-detected` means a credential is embedded; do not
  122. retry with `--allow-secrets` unless the user explicitly wants that risk.
  123. 5. A repository may contain several resources; the importer imports each typed
  124. candidate. Use `--type skill` / `--type plugin` / `--kinds` to narrow.
  125. 6. Distribute only after import succeeded (workflow C).
  126. ## Workflow B - scan tools and import their resources
  127. ```bash
  128. python scripts/sync_resources.py --direction import --agent claude --agent codex --json
  129. python scripts/sync_resources.py --direction import --json # all six tools
  130. python scripts/sync_resources.py --direction import --workspace . # project scope
  131. ```
  132. Actions: `imported` (new), `imported-update` (state B, target changed only, a new
  133. library version is created), `skip` (identical or library ahead),
  134. `conflict` (state C, exit 2), `needs-confirmation` / `rejected` (unsafe or invalid).
  135. When `conflict` appears, do not force. Run workflow E.
  136. ## Workflow C - distribute library resources
  137. ```bash
  138. python scripts/sync_resources.py --direction distribute \
  139. --agent dsh --agent codex --agent claude --resource <id-or-name> --json
  140. python scripts/sync_resources.py --direction distribute --all --json
  141. ```
  142. - `--mode copy` is the default and the only universally safe mode.
  143. - `--mode link` creates a junction/symlink to the library payload. Verify with
  144. `verify_sync.py` afterwards; the link mode has only been verified on Windows
  145. junctions, not on every platform/tool combination.
  146. - Skills are portable. Plugins are **not**: the engine refuses cross-tool plugin
  147. copies and returns a `manual` action with the exact per-tool install command.
  148. Present that command, explain where it installs, and let the user run it or
  149. approve running it. Never copy plugin files into another tool's skills folder.
  150. - Before planning a plugin install, inventory what is already installed:
  151. `python scripts/detect_resources.py --agent <id> --kinds plugins --json`
  152. lists installed plugins with versions and cache paths (Claude
  153. `installed_plugins.json`, Codex `config.toml` + cache, DSH profile bundles, Gemini
  154. extensions, VS Code extensions contributing `chatSkills`). Report version drift
  155. between tools and never hand-copy a plugin cache directory.
  156. - MCP resources are merged into the target JSON config with secret redaction.
  157. Codex stores MCP in TOML; automated writes are intentionally not implemented,
  158. so the result is manual with a config snippet.
  159. - Rules: dedicated rule folders get a new managed file; shared instruction
  160. files (AGENTS.md / CLAUDE.md / GEMINI.md) are never modified when they already
  161. exist - the result is `manual` with a managed block to append.
  162. ## Workflow D - two-way sync
  163. ```bash
  164. python scripts/sync_resources.py --direction both --agent codex --json
  165. ```
  166. Import first, then distribute. Both directions are idempotent: identical content
  167. is skipped without writes or backups. Use `--resume` after an interrupted run; the
  168. journal under `staging/journal-*.json` records completed steps.
  169. ## Workflow E - conflict review and resolution
  170. 1. Explain the state (A/B/C/D/E) using `references/conflict-resolution.md`.
  171. 2. Show the difference:
  172. `python scripts/compare_resources.py --left resource:<name> --right agent:<agent>:<name> --diff`
  173. For two stored versions use `resource:<name>@<version-label>`.
  174. 3. Offer exactly these resolutions:
  175. - **keep library** - distribute to the target with `--on-conflict library` (backup first).
  176. - **keep target** - capture the target as a new library version:
  177. `import_resource.py --source <target-path> --on-conflict keep-source` or
  178. `sync_resources.py --direction import --on-conflict new-version`.
  179. On the distribute side `--on-conflict target` means "leave it alone" (`kept-target`).
  180. - **manual merge** - show both files, let the user edit the library payload,
  181. then distribute and verify. This skill does not auto-merge text.
  182. - **save as new version** - import with `--on-conflict new-version`.
  183. 4. After resolving, run `verify_sync.py` and report both versions and hashes.
  184. 5. Never pick a resolution silently. State C means both sides changed on purpose;
  185. the user owns that decision.
  186. ## Workflow F - verify and repair
  187. ```bash
  188. python scripts/verify_sync.py --all --json
  189. python scripts/verify_sync.py --resource <name> --include-unmanaged --json
  190. ```
  191. Statuses: `ok`, `drifted` (file list included), `missing`, `corrupted` (bad link),
  192. `umanaged` (present in a tool, absent from the library), `unavailable`.
  193. Repair = re-distribute when the library is authoritative, or import when the
  194. target is authoritative. Both are conflict-guarded, so decide the direction with
  195. the user first.
  196. ## Workflow G - backup and restore
  197. ```bash
  198. python scripts/backup_restore.py backup --resource <name>
  199. python scripts/backup_restore.py list
  200. python scripts/backup_restore.py restore --backup-id <id> --to library
  201. python scripts/backup_restore.py restore --resource <name> --version <label>
  202. python scripts/backup_restore.py prune --keep 10
  203. ```
  204. Global flags (`--home`, `--json`) go **before** the subcommand. Every restore snapshots
  205. the current state first, so restores are undoable.
  206. ## Workflow H - plugin distribution (planning only)
  207. Plugins are tool-specific packages. The engine:
  208. 1. detects the packaging (e.g. `.claude-plugin/plugin.json`, `package.json#dsh`,
  209. `gemini-extension.json`, `.cursor-plugin/plugin.json`),
  210. 2. refuses cross-tool copies,
  211. 3. returns the target tool's real install mechanism and command, e.g.
  212. `dsh plugin --profile desktop add <npm-package>` or
  213. `claude plugin install <plugin>@<marketplace>`.
  214. The skill does not execute package installs by default. Show the command, the
  215. marketplace/source, and the restart requirement; ask before running it. A DSH
  216. Plugin for this system is specified in `references/dsh-plugin-spec.md` but is
  217. **not implemented** - do not call or advertise it.
  218. ## Safety review checklist (before any install)
  219. - Source: official repo? star/age/owner? does the README match the code?
  220. - Files: what scripts/binaries/hooks ship? any `postinstall` / `setup.py` / `.pth`?
  221. - Commands: piping downloads into a shell, recursive deletes, privilege
  222. escalation, persistence, credential access, network exfiltration.
  223. - Data: does it read `.ssh`, browser profiles, token stores, env dumps?
  224. - Permissions: does the target tool need a restart? does it read project or user
  225. scope? does the user want a global or workspace install?
  226. - Reversibility: a backup exists? is uninstall documented?
  227. Report risk as high/medium/low with concrete evidence, then ask.
  228. ## Result report (always end with this shape)
  229. ```markdown
  230. ## Operation report
  231. - Request: <what the user asked>
  232. - Environment: <tool status + versions + library root>
  233. - Classification: <type, source, version/hash, supported tools>
  234. - Security: <risk, findings, secret handling, confirmation given>
  235. - Actions: <imported / installed / skipped / manual / conflict, per tool>
  236. - Verification: <verify status per target, hashes compared>
  237. - Conflicts/backups: <paths>
  238. - Not done / unverified: <honest list>
  239. - Next step: <one concrete action>
  240. ```
  241. ## Failure playbook
  242. | Symptom | Meaning | Action |
  243. |---|---|---|
  244. | exit 2 on sync/import | conflict (including dry runs), nothing overwritten | workflow E |
  245. | `git-rewrite-detected` | git insteadOf redirects official hosts to a mirror | show the rule; `--allow-mirror` only if trusted |
  246. | PermissionError / access denied on the library root | default `~/.ai-extension-manager` is not writable here | re-run with `--home <writable-dir>`, tell the user the root used |
  247. | `kept-target` | explicit keep-target resolution | run the import direction when the user wants it in the library |
  248. | `unavailable` for a tool | tool absent or no verified dir | stop, offer alternatives |
  249. | `error write failed` | blocked path/permission | report path, do not retry blindly; ask for a writable location |
  250. | `needs-confirmation` | scanner found risk | show findings, ask, then `--allow-risk` |
  251. | `secret-detected` | credential in payload | scrub or refuse; never store it |
  252. | `invalid` skill | SKILL.md fails the open standard | fix name/description or use `--force` only if the user accepts a non-standard skill |
  253. | hash mismatch after write | storage problem | report, restore from backup, do not claim success |
  254. ## Environment facts this skill was built against
  255. Verified on the authoring machine: DSH 0.2.0-rc.2, Claude Code 2.1.318,
  256. Codex config-only (no CLI on PATH), VS Code 1.115.0, Gemini CLI and Cursor not
  257. installed. Re-verify with `scan_agents.py` on every new machine; paths and
  258. capabilities are data, not assumptions.
  259. ## 中文速查(给中文用户)
  260. 完整中文说明见 [README.zh-CN.md](README.zh-CN.md) 与 [references/cli-reference.md](references/cli-reference.md)。
  261. ```bash
  262. python -m pip install . # 安装 aem 命令
  263. python scripts/aem.py <命令> # 或不安装直接运行
  264. aem init && aem doctor && aem scan # 建库、体检、探测六个工具
  265. ```
  266. | 用户说 | 执行 |
  267. |---|---|
  268. | 把这个 GitHub 上的 Skill 装到 DSH/Codex/Claude | 先 `aem detect --url <url>` 识别类型与风险,再 `aem import --source <url>`,然后 `aem sync --direction distribute --agent ... --resource ...`,最后 `aem verify --all` |
  269. | 把六个工具新增的 Skill 导入中央库 | `aem adopt`(等价于 `aem sync --direction import --all-agents`),冲突时报告并停下,不覆盖 |
  270. | 检查哪些副本漂移/损坏 | `aem verify --all` 或 `aem status --strict` |
  271. | 回滚某个资源 | `aem backups` 找到快照,再 `aem restore --resource <名> --version <标签>` |
  272. | 两边都改过怎么办 | 不自动合并;给出 `aem compare --diff` 证据,让用户选保留中央库、保留目标、手动合并或另存新版本 |
  273. 默认不覆盖、先备份、危险操作要确认。DSH Plugin 面板尚未实现,不要声称存在。
README.md · README · 254 lines
  1. # AI Extension Manager
  2. **English** | [简体中文](README.zh-CN.md)
  3. ### One library. Six AI tools. Two-way sync that never silently overwrites your work.
  4. `aem` keeps your Agent Skills, rules and MCP server definitions in one local library and syncs
  5. them to Claude Code, OpenAI Codex, Gemini CLI, Cursor, VS Code Copilot and DSH. It decides what
  6. changed using SHA-256 content hashes and per-target sync records — never "the newest file wins".
  7. **Website:** <https://jack91124.github.io/ai-extension-manager/> · [中文落地页](https://jack91124.github.io/ai-extension-manager/zh.html)
  8. [![Website](https://img.shields.io/badge/website-live-5eead4)](https://jack91124.github.io/ai-extension-manager/)
  9. [![skills.sh](https://skills.sh/b/Jack91124/ai-extension-manager)](https://www.skills.sh/jack91124/ai-extension-manager)
  10. ![Python](https://img.shields.io/badge/python-3.9%2B-blue)
  11. ![Dependencies](https://img.shields.io/badge/dependencies-none-brightgreen)
  12. ![License](https://img.shields.io/badge/license-MIT-green)
  13. ![Tests](https://img.shields.io/badge/scenario%20tests-25%20passing-brightgreen)
  14. [![CI](https://github.com/Jack91124/ai-extension-manager/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Jack91124/ai-extension-manager/actions/workflows/ci.yml)
  15. [![Release](https://img.shields.io/github/v/release/Jack91124/ai-extension-manager?color=blue)](https://github.com/Jack91124/ai-extension-manager/releases/latest)
  16. ![Platforms](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)
  17. **Quick start** · [Why](#why-another-skill-manager) · [60-second workflow](#the-60-second-workflow) ·
  18. [Conflict model](#how-conflicts-work) · [Support matrix](#what-is-supported-today) ·
  19. [Safety](#safety-by-default) · [CLI](#cli-at-a-glance) · [Demo](demo/) · [Docs](#documentation)
  20. ---
  21. ## Why another skill manager?
  22. Every AI coding tool invented its own folder: `~/.claude/skills`, `~/.codex/skills`,
  23. `~/.gemini/skills`, `~/.cursor/skills`, `~/.copilot/skills`, `~/.dsh/skills`. In practice that means:
  24. - the same skill is copied five times, then edited in three places;
  25. - installing a skill for one tool leaves the other five behind;
  26. - a "sync" script copies files and silently deletes last week's local fix;
  27. - no one can answer "which tools have version 1.2 of this skill, and did any copy drift?"
  28. `aem` treats a **central library as the source of truth** and records exactly what was distributed
  29. to each tool. That record is what lets it distinguish "only the library changed" from "only the tool
  30. changed" from "both changed" — and refuse to guess in the last case.
  31. It is deliberately **local-first**: plain files, plain JSON, no server, no telemetry, no account.
  32. ![aem demo: import, distribute to two tools, verify, then a state-C conflict that writes nothing](docs/demo.gif)
  33. <sub>10-second demo, rendered from the real `demo/run_demo.py` transcript ([static version](docs/hero.png), [how it is made](docs/make_demo_gif.py)).</sub>
  34. ## Quick start
  35. Requires **Python 3.9+**. No third-party packages, on Windows, macOS or Linux.
  36. Install without cloning (needs `git`; pin the tag for a reproducible install):
  37. ```bash
  38. python -m pip install --user "git+https://github.com/Jack91124/ai-extension-manager.git@v1.0.3"
  39. aem init && aem doctor
  40. ```
  41. Prefer an isolated CLI? Use `pipx install "git+https://github.com/Jack91124/ai-extension-manager.git@v1.0.3"`,
  42. or download the wheel from the [latest release](https://github.com/Jack91124/ai-extension-manager/releases/latest)
  43. and `pip install` it.
  44. Or clone the repository:
  45. ```bash
  46. git clone https://github.com/Jack91124/ai-extension-manager.git
  47. cd ai-extension-manager
  48. python -m pip install .
  49. aem init # create ~/.ai-extension-manager
  50. aem doctor # check Python, paths, registry, locks and installed tools
  51. aem scan # detect the six tools and their skill folders
  52. ```
  53. No install needed — every command also runs as `python scripts/aem.py <command>`.
  54. Already use the [`skills`](https://github.com/vercel-labs/skills) CLI? Install it as an agent skill
  55. (Node 22.20+), which also lists it on [skills.sh](https://www.skills.sh/jack91124/ai-extension-manager):
  56. ```bash
  57. npx skills add Jack91124/ai-extension-manager
  58. ```
  59. The repository root is a valid skill, so the CLI installs the whole toolkit (docs, scripts, evals)
  60. into `.claude/skills/ai-extension-manager` or `.agents/skills/ai-extension-manager`.
  61. A real `aem doctor` run on a Windows machine where three of the six tools are installed:
  62. ```text
  63. $ aem doctor
  64. [ok] python 3.14.4 (requires 3.9+)
  65. [ok] library C:\Users\you\.ai-extension-manager is writable
  66. [ok] registry 0 resources
  67. [ok] schema schema 1
  68. [ok] payloads all payload directories present
  69. [ok] lock no library lock
  70. [ok] agents 3/6 tools installed; absent: gemini, cursor
  71. [ok] disk 132.4GB free
  72. [ok] backups 0 snapshots, 0B
  73. [ok] conflicts 0 unresolved conflict(s)
  74. result: healthy
  75. ```
  76. ## The 60-second workflow
  77. ```bash
  78. # 1. bring a skill in from GitHub or a local folder
  79. aem import --source https://github.com/owner/repo/tree/main/skills/my-skill
  80. # 2. send it to the tools that need it (repeatable --agent)
  81. aem sync --direction distribute --agent claude --agent codex --resource my-skill
  82. # 3. prove the copies match the library
  83. aem verify --all
  84. aem status
  85. ```
  86. Everything is reversible: `aem backups` lists snapshots, `aem restore` brings back an old version,
  87. `aem compare` shows a unified diff between a library version, an old snapshot and a tool's copy.
  88. Want to edit a skill inside one tool and pull the change back? `aem sync --direction both` imports
  89. target-side changes that are safe, and stops with exit code `2` when both sides changed.
  90. ## How conflicts work
  91. Each resource stores a SHA-256 tree hash. Each target stores the hash it was synced from
  92. (`source_hash`), the hash it received (`target_hash`) and `synced_at`. From those three facts:
  93. | State | What happened | Default action |
  94. |---|---|---|
  95. | **A** | only the library changed | update the target (after a backup) |
  96. | **B** | only the target changed | keep the target, suggest importing it |
  97. | **C** | both sides changed | **conflict: write nothing, exit 2** |
  98. | **D** | the target was deleted | report missing, do not recreate silently |
  99. | **E** | the target directory does not exist | report unavailable, do not invent a path |
  100. | untracked | a copy exists that was never synced | identical → adopt; different → conflict |
  101. Conflicts are stored under `conflicts/` with the evidence (hashes, path, timestamp). Resolve them
  102. explicitly:
  103. ```bash
  104. aem compare --left resource:my-skill --right agent:claude:my-skill --diff
  105. aem sync --direction distribute --agent claude --resource my-skill --on-conflict library # keep library
  106. aem sync --direction import --agent claude --on-conflict new-version # keep target as a new version
  107. aem restore --resource my-skill --version <label> # roll back
  108. ```
  109. Nothing is overwritten by default — not on conflict, not on first contact with an untracked copy.
  110. The long version of this argument (why mtime is not a conflict policy, and what it costs to get it
  111. wrong) is in [docs/why-sync-overwrites.md](docs/why-sync-overwrites.md).
  112. ## What is supported today
  113. | Tool | Skills | Rules | MCP | Plugins | Verification |
  114. |---|---|---|---|---|---|
  115. | **Claude Code** | copy / link | `CLAUDE.md` | JSON merge | marketplace command | tested locally (CLI 2.1.318) |
  116. | **OpenAI Codex** | copy / link | `AGENTS.md` | manual (TOML) | marketplace command | config dir tested; CLI not installed |
  117. | **DSH** | copy / link | `AGENTS.md` | via plugins | `dsh plugin add` | tested locally (0.2.0-rc.2) |
  118. | **Gemini CLI** | copy / link | `GEMINI.md` | JSON merge | `gemini extensions install` | official docs; runtime not exercised |
  119. | **Cursor** | copy / link | `.cursor/rules` | JSON merge | marketplace UI only | paths partial (not installed) |
  120. | **VS Code / Copilot** | copy / link | instructions files | JSON merge | VS Code extensions | docs + local VS Code 1.115 |
  121. Plugin code is **never copied across tools**. A plugin is installed through its target tool's own
  122. mechanism; `aem` returns the exact command and refuses cross-tool moves for tool-specific plugins.
  123. ## Safety by default
  124. - **Scans before import** — dangerous shell patterns, risky scripts, secrets; high risk requires
  125. `--allow-risk`, credentials are refused (or rewritten to `${ENV_VAR}` placeholders for MCP).
  126. - **Backs up before overwriting** any target or library payload.
  127. - **Never deletes** another tool's resource without an explicit uninstall/restore command.
  128. - **Refuses git URL rewrites** that would redirect `github.com` to a third-party mirror
  129. (`--allow-mirror` to override).
  130. - **No secret exfiltration** — the library is local; `metadata/registry.json` stores hashes, not keys.
  131. - **Dry runs everywhere** — `--dry-run` shows the plan and leaves no journal behind.
  132. Read the full policy in [references/security-policy.md](references/security-policy.md).
  133. ## CLI at a glance
  134. | Command | What it does |
  135. |---|---|
  136. | `aem init` | create the library layout |
  137. | `aem doctor` | diagnose Python, paths, registry, schema, locks, tools, disk |
  138. | `aem status` | one table of every resource × tool, `--strict` fails on drift |
  139. | `aem scan` | detect tools, versions and skill folders |
  140. | `aem detect --path P` | classify P as skill / plugin / MCP / rules |
  141. | `aem import --source P` | import a local path or GitHub URL |
  142. | `aem sync --direction import\|distribute\|both` | two-way sync with conflict detection |
  143. | `aem adopt` | shortcut for import: pull every tool's new/changed resources in |
  144. | `aem distribute` | shortcut for distribute: push library resources to tools (backs up first) |
  145. | `aem compare --left A --right B --diff` | hash inventory + unified diff |
  146. | `aem verify --all` | verify installed copies against the library |
  147. | `aem backup` / `aem backups` / `aem restore` / `aem prune` | snapshots and rollback |
  148. Every command accepts `--home`, `--workspace` and `--json`. Exit codes: `0` success,
  149. `1` error, `2` conflict or difference. See [references/cli-reference.md](references/cli-reference.md).
  150. ## Demo
  151. The repository ships a self-contained demo that never touches your real tool folders:
  152. ```bash
  153. python demo/run_demo.py
  154. ```
  155. It creates a fake library and six fake tool homes, imports a skill, distributes it to three tools,
  156. verifies the hashes, edits one copy, shows the drift, edits the upstream copy, and ends with a real
  157. state-C conflict that it refuses to overwrite. The full captured transcript is in
  158. [demo/demo-output.txt](demo/demo-output.txt).
  159. ## Documentation
  160. | Document | Contents |
  161. |---|---|
  162. | [SKILL.md](SKILL.md) | the agent-facing skill: when to use it, decision rules, command recipes |
  163. | [references/architecture.md](references/architecture.md) | layers, data model, directory layout |
  164. | [references/resource-types.md](references/resource-types.md) | skill / plugin / MCP / rules compatibility |
  165. | [references/agent-compatibility.md](references/agent-compatibility.md) | per-tool paths and verification status |
  166. | [references/synchronization-engine.md](references/synchronization-engine.md) | import/distribute protocol, state machine |
  167. | [references/conflict-resolution.md](references/conflict-resolution.md) | A–E states and resolution playbook |
  168. | [references/security-policy.md](references/security-policy.md) | scanning, secrets, confirmations |
  169. | [references/installation-methods.md](references/installation-methods.md) | copy vs link vs tool-native install |
  170. | [references/dsh-plugin-spec.md](references/dsh-plugin-spec.md) | the planned GUI/execution plugin (not built) |
  171. | [docs/launch.md](docs/launch.md) | launch positioning, copy and channel checklist |
  172. | [docs/ROADMAP.md](docs/ROADMAP.md) | where this is going |
  173. ## Status and limits
  174. This is a working **v1.0 CLI + Agent Skill**, not a finished product:
  175. - ✅ import, distribute, both-way sync, conflict detection, backups, verify, compare, restore;
  176. - ✅ six adapters with honest verification levels, safety scanner, JSON contracts;
  177. - ✅ 25 scenario tests on disposable fake homes;
  178. - 🚧 DSH Plugin dashboard is **specified, not implemented** — no GUI is claimed here;
  179. - 🚧 plugin installation is delegated to each tool's native command (no auto-install yet);
  180. - ⚠️ Gemini CLI and Cursor were verified against official docs/path maps, not exercised at runtime;
  181. - ⚠️ Codex MCP writes are manual (TOML rewriting is intentionally not automated).
  182. ## Contributing
  183. Issues and pull requests are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) and
  184. [SECURITY.md](SECURITY.md). The scenario suite runs with plain Python:
  185. ```bash
  186. python evals/run_tests.py
  187. ```
  188. ## License
  189. MIT — see [LICENSE](LICENSE).
  190. Gitee mirror: <https://gitee.com/ping-pong-squid-king/ai-extension-manager.git>

Ratings and comments

Sign in to rate this skill.

Sign in

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