ai-extension-manager
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
Markdown
[](/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
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
- ---
- name: ai-extension-manager
- description: >-
- 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.
- license: MIT
- 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.
- allowed-tools: Read Write Edit Bash Glob Grep
- metadata:
- display_name: AI Extension Manager
- display_name_zh: AI 扩展资源管理助手
- version: 1.0.4
- category: developer-tools
- phase: v1.0 (CLI + Agent Skill; DSH Plugin specified, not built)
- ---
- # AI Extension Manager
- One central library, six AI tools, two-way synchronization. This skill is the
- **decision layer**: it classifies a resource, checks compatibility and safety,
- plans the change, executes it through the bundled Python tools (or the DSH
- Plugin once one exists), verifies the result and reports it.
- The bundled scripts are the only execution layer that exists today. There is no
- graphical DSH Plugin yet. Never claim that a plugin UI, a plugin tool, or a
- native API of another AI tool is available unless the environment scan proves it.
- ## Install and run
- The stable entry point is `aem`; the seven Python scripts remain the implementation.
- ```bash
- python -m pip install . # from a source checkout; installs the `aem` command
- aem init # create ~/.ai-extension-manager
- aem doctor # check Python, paths, registry, locks and tools
- aem status # resource x agent sync state
- ```
- Without installing, every command also works as `python scripts/aem.py <command>`.
- | Command | Purpose |
- |---|---|
- | `aem scan` | detect the six tools and their skill directories |
- | `aem detect --path P` | classify P as skill / plugin / MCP / rules |
- | `aem import --source P` | import into the central library |
- | `aem sync --direction distribute --agent claude --agent codex --resource NAME` | distribute |
- | `aem adopt` / `aem distribute` | one-word shortcuts for the two sync directions |
- | `aem verify --all` | verify installed copies |
- | `aem status` | one table of every resource x agent pair |
- | `aem doctor` | diagnose setup problems with fixes |
- All commands accept `--home`, `--workspace` and `--json`; see `references/cli-reference.md`.
- ## Non-negotiable rules
- 1. **Detect before you touch.** Run `scripts/scan_agents.py` first. Never guess a tool's
- directory, version or capability; the registry marks every path as
- local / official / partial / unverified.
- 2. **No silent overwrite.** Any existing file or resource that differs from the
- incoming content is a conflict. Conflicts require an explicit resolution
- (keep library / keep target / manual merge / save as new version). The scripts
- exit 2 and store evidence instead of overwriting.
- 3. **Back up before replacing.** The engine snapshots the target and the library
- version before every write. Backups live under `<home>/backups/`.
- 4. **Review before installing code.** Run the built-in safety scan, read the
- scripts that will ship, and get explicit user confirmation for high/medium
- risk resources or for anything that installs packages, runs shell commands,
- or ships binaries.
- 5. **Secrets never enter the library.** Credentials found in skills are refused;
- credentials in MCP configs are replaced with `${ENV_VAR}` placeholders and the
- user must export the variable. Never echo a secret into a report.
- 6. **Honest capability reporting.** If a tool is absent, a plugin mechanism is
- unverified, or a distribution path is not implemented, say so and stop. A
- partial result reported accurately is better than a fake success.
- ## Establish context (run first, every session)
- ```bash
- python scripts/scan_agents.py --json
- python scripts/scan_agents.py --workspace <project> --json # adds project-scope dirs
- ```
- Both scan commands are read-only: they never create the central library. The first
- mutating command creates it. If the default location is not writable (sandboxed
- hosts, read-only home), pass `--home <writable-dir>` and tell the user which root you used.
- Use the JSON: tool status (installed / config-only / absent), CLI version, skill
- directories and their counts, plugin system, MCP and rules capability, plus
- `verification` flags. Record the central library root: it defaults to
- `$AEM_HOME` or `~/.ai-extension-manager`. Pass `--home` when the user wants another location.
- If the request names a specific tool that is `absent`, say so immediately and offer
- one of: install the resource somewhere present, prepare a portable copy, or stop.
- Do not create directories inside a tool that is not installed.
- ## Pick the workflow
- | User intent | Workflow | Primary commands |
- |---|---|---|
- | "install this GitHub skill / plugin" | A. Install from source | `detect_resources.py --url` then `import_resource.py` |
- | "what's new in my AI tools?" | B. Scan and import | `sync_resources.py --direction import` |
- | "sync this skill to Codex and Claude" | C. Distribute | `sync_resources.py --direction distribute --agent ...` |
- | "make all tools match the library" | D. Two-way sync | `sync_resources.py --direction both` |
- | "these copies disagree" | E. Conflict review | `compare_resources.py` + manual decision |
- | "is the install still correct?" | F. Verify / repair | `verify_sync.py` then re-distribute |
- | "roll back / restore" | G. Backups | `backup_restore.py` |
- | "install this plugin for me" | H. Plugin planning | plugin action is a plan + command, see below |
- | "what do I have?" | I. Inventory report | `detect_resources.py --all-agents` + registry |
- Detailed contracts live in `references/`; read only what the task needs:
- - `architecture.md` - layers, Skill/Plugin boundary, operation contract
- - `resource-types.md` - classification signals, record schema, payload layout
- - `agent-compatibility.md` - verified paths and capabilities per tool
- - `synchronization-engine.md` - state machine, modes, journal, idempotency
- - `conflict-resolution.md` - detection math and resolution procedures
- - `security-policy.md` - scanner rules, confirmation gates, secret handling
- - `installation-methods.md` - per-tool install/uninstall mechanics
- - `dsh-plugin-spec.md` - specification for the future dashboard plugin
- ## Workflow A - install from a GitHub URL or local path
- 1. Classify the source **before** downloading when possible:
- `python scripts/detect_resources.py --url <url> --json`
- The result says whether the URL is a repository, which host it is, and the
- exact import command. Recognised types: `skill`, `plugin`, `mcp`, `rules`.
- 2. Before any remote import, the tool audits git `url.*.insteadOf` rewrites. A rule
- that sends github.com clones to a third-party mirror is refused with
- `git-rewrite-detected` (exit 1): show the rule and ask; only pass `--allow-mirror`
- if the user trusts that mirror. A URL dry run still clones into `staging/`
- (classification needs the files) and cleans up afterwards; local paths have no
- such side effect.
- 3. For a remote repo, import with conflict policy and a dry run first:
- `python scripts/import_resource.py --source <url> --dry-run --json`
- Then run without `--dry-run`. The clone is shallow and goes to `staging/`.
- 4. Read the JSON result. `needs-confirmation` means the security scanner found
- shell piping, recursive deletes, binary payloads or other risky patterns:
- summarize the findings, show the file and line, and ask before re-running
- with `--allow-risk`. `secret-detected` means a credential is embedded; do not
- retry with `--allow-secrets` unless the user explicitly wants that risk.
- 5. A repository may contain several resources; the importer imports each typed
- candidate. Use `--type skill` / `--type plugin` / `--kinds` to narrow.
- 6. Distribute only after import succeeded (workflow C).
- ## Workflow B - scan tools and import their resources
- ```bash
- python scripts/sync_resources.py --direction import --agent claude --agent codex --json
- python scripts/sync_resources.py --direction import --json # all six tools
- python scripts/sync_resources.py --direction import --workspace . # project scope
- ```
- Actions: `imported` (new), `imported-update` (state B, target changed only, a new
- library version is created), `skip` (identical or library ahead),
- `conflict` (state C, exit 2), `needs-confirmation` / `rejected` (unsafe or invalid).
- When `conflict` appears, do not force. Run workflow E.
- ## Workflow C - distribute library resources
- ```bash
- python scripts/sync_resources.py --direction distribute \
- --agent dsh --agent codex --agent claude --resource <id-or-name> --json
- python scripts/sync_resources.py --direction distribute --all --json
- ```
- - `--mode copy` is the default and the only universally safe mode.
- - `--mode link` creates a junction/symlink to the library payload. Verify with
- `verify_sync.py` afterwards; the link mode has only been verified on Windows
- junctions, not on every platform/tool combination.
- - Skills are portable. Plugins are **not**: the engine refuses cross-tool plugin
- copies and returns a `manual` action with the exact per-tool install command.
- Present that command, explain where it installs, and let the user run it or
- approve running it. Never copy plugin files into another tool's skills folder.
- - Before planning a plugin install, inventory what is already installed:
- `python scripts/detect_resources.py --agent <id> --kinds plugins --json`
- lists installed plugins with versions and cache paths (Claude
- `installed_plugins.json`, Codex `config.toml` + cache, DSH profile bundles, Gemini
- extensions, VS Code extensions contributing `chatSkills`). Report version drift
- between tools and never hand-copy a plugin cache directory.
- - MCP resources are merged into the target JSON config with secret redaction.
- Codex stores MCP in TOML; automated writes are intentionally not implemented,
- so the result is manual with a config snippet.
- - Rules: dedicated rule folders get a new managed file; shared instruction
- files (AGENTS.md / CLAUDE.md / GEMINI.md) are never modified when they already
- exist - the result is `manual` with a managed block to append.
- ## Workflow D - two-way sync
- ```bash
- python scripts/sync_resources.py --direction both --agent codex --json
- ```
- Import first, then distribute. Both directions are idempotent: identical content
- is skipped without writes or backups. Use `--resume` after an interrupted run; the
- journal under `staging/journal-*.json` records completed steps.
- ## Workflow E - conflict review and resolution
- 1. Explain the state (A/B/C/D/E) using `references/conflict-resolution.md`.
- 2. Show the difference:
- `python scripts/compare_resources.py --left resource:<name> --right agent:<agent>:<name> --diff`
- For two stored versions use `resource:<name>@<version-label>`.
- 3. Offer exactly these resolutions:
- - **keep library** - distribute to the target with `--on-conflict library` (backup first).
- - **keep target** - capture the target as a new library version:
- `import_resource.py --source <target-path> --on-conflict keep-source` or
- `sync_resources.py --direction import --on-conflict new-version`.
- On the distribute side `--on-conflict target` means "leave it alone" (`kept-target`).
- - **manual merge** - show both files, let the user edit the library payload,
- then distribute and verify. This skill does not auto-merge text.
- - **save as new version** - import with `--on-conflict new-version`.
- 4. After resolving, run `verify_sync.py` and report both versions and hashes.
- 5. Never pick a resolution silently. State C means both sides changed on purpose;
- the user owns that decision.
- ## Workflow F - verify and repair
- ```bash
- python scripts/verify_sync.py --all --json
- python scripts/verify_sync.py --resource <name> --include-unmanaged --json
- ```
- Statuses: `ok`, `drifted` (file list included), `missing`, `corrupted` (bad link),
- `umanaged` (present in a tool, absent from the library), `unavailable`.
- Repair = re-distribute when the library is authoritative, or import when the
- target is authoritative. Both are conflict-guarded, so decide the direction with
- the user first.
- ## Workflow G - backup and restore
- ```bash
- python scripts/backup_restore.py backup --resource <name>
- python scripts/backup_restore.py list
- python scripts/backup_restore.py restore --backup-id <id> --to library
- python scripts/backup_restore.py restore --resource <name> --version <label>
- python scripts/backup_restore.py prune --keep 10
- ```
- Global flags (`--home`, `--json`) go **before** the subcommand. Every restore snapshots
- the current state first, so restores are undoable.
- ## Workflow H - plugin distribution (planning only)
- Plugins are tool-specific packages. The engine:
- 1. detects the packaging (e.g. `.claude-plugin/plugin.json`, `package.json#dsh`,
- `gemini-extension.json`, `.cursor-plugin/plugin.json`),
- 2. refuses cross-tool copies,
- 3. returns the target tool's real install mechanism and command, e.g.
- `dsh plugin --profile desktop add <npm-package>` or
- `claude plugin install <plugin>@<marketplace>`.
- The skill does not execute package installs by default. Show the command, the
- marketplace/source, and the restart requirement; ask before running it. A DSH
- Plugin for this system is specified in `references/dsh-plugin-spec.md` but is
- **not implemented** - do not call or advertise it.
- ## Safety review checklist (before any install)
- - Source: official repo? star/age/owner? does the README match the code?
- - Files: what scripts/binaries/hooks ship? any `postinstall` / `setup.py` / `.pth`?
- - Commands: piping downloads into a shell, recursive deletes, privilege
- escalation, persistence, credential access, network exfiltration.
- - Data: does it read `.ssh`, browser profiles, token stores, env dumps?
- - Permissions: does the target tool need a restart? does it read project or user
- scope? does the user want a global or workspace install?
- - Reversibility: a backup exists? is uninstall documented?
- Report risk as high/medium/low with concrete evidence, then ask.
- ## Result report (always end with this shape)
- ```markdown
- ## Operation report
- - Request: <what the user asked>
- - Environment: <tool status + versions + library root>
- - Classification: <type, source, version/hash, supported tools>
- - Security: <risk, findings, secret handling, confirmation given>
- - Actions: <imported / installed / skipped / manual / conflict, per tool>
- - Verification: <verify status per target, hashes compared>
- - Conflicts/backups: <paths>
- - Not done / unverified: <honest list>
- - Next step: <one concrete action>
- ```
- ## Failure playbook
- | Symptom | Meaning | Action |
- |---|---|---|
- | exit 2 on sync/import | conflict (including dry runs), nothing overwritten | workflow E |
- | `git-rewrite-detected` | git insteadOf redirects official hosts to a mirror | show the rule; `--allow-mirror` only if trusted |
- | 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 |
- | `kept-target` | explicit keep-target resolution | run the import direction when the user wants it in the library |
- | `unavailable` for a tool | tool absent or no verified dir | stop, offer alternatives |
- | `error write failed` | blocked path/permission | report path, do not retry blindly; ask for a writable location |
- | `needs-confirmation` | scanner found risk | show findings, ask, then `--allow-risk` |
- | `secret-detected` | credential in payload | scrub or refuse; never store it |
- | `invalid` skill | SKILL.md fails the open standard | fix name/description or use `--force` only if the user accepts a non-standard skill |
- | hash mismatch after write | storage problem | report, restore from backup, do not claim success |
- ## Environment facts this skill was built against
- Verified on the authoring machine: DSH 0.2.0-rc.2, Claude Code 2.1.318,
- Codex config-only (no CLI on PATH), VS Code 1.115.0, Gemini CLI and Cursor not
- installed. Re-verify with `scan_agents.py` on every new machine; paths and
- capabilities are data, not assumptions.
- ## 中文速查(给中文用户)
- 完整中文说明见 [README.zh-CN.md](README.zh-CN.md) 与 [references/cli-reference.md](references/cli-reference.md)。
- ```bash
- python -m pip install . # 安装 aem 命令
- python scripts/aem.py <命令> # 或不安装直接运行
- aem init && aem doctor && aem scan # 建库、体检、探测六个工具
- ```
- | 用户说 | 执行 |
- |---|---|
- | 把这个 GitHub 上的 Skill 装到 DSH/Codex/Claude | 先 `aem detect --url <url>` 识别类型与风险,再 `aem import --source <url>`,然后 `aem sync --direction distribute --agent ... --resource ...`,最后 `aem verify --all` |
- | 把六个工具新增的 Skill 导入中央库 | `aem adopt`(等价于 `aem sync --direction import --all-agents`),冲突时报告并停下,不覆盖 |
- | 检查哪些副本漂移/损坏 | `aem verify --all` 或 `aem status --strict` |
- | 回滚某个资源 | `aem backups` 找到快照,再 `aem restore --resource <名> --version <标签>` |
- | 两边都改过怎么办 | 不自动合并;给出 `aem compare --diff` 证据,让用户选保留中央库、保留目标、手动合并或另存新版本 |
- 默认不覆盖、先备份、危险操作要确认。DSH Plugin 面板尚未实现,不要声称存在。
README.md · README · 254 lines
- # AI Extension Manager
- **English** | [简体中文](README.zh-CN.md)
- ### One library. Six AI tools. Two-way sync that never silently overwrites your work.
- `aem` keeps your Agent Skills, rules and MCP server definitions in one local library and syncs
- them to Claude Code, OpenAI Codex, Gemini CLI, Cursor, VS Code Copilot and DSH. It decides what
- changed using SHA-256 content hashes and per-target sync records — never "the newest file wins".
- **Website:** <https://jack91124.github.io/ai-extension-manager/> · [中文落地页](https://jack91124.github.io/ai-extension-manager/zh.html)
- [](https://jack91124.github.io/ai-extension-manager/)
- [](https://www.skills.sh/jack91124/ai-extension-manager)
- 
- 
- 
- 
- [](https://github.com/Jack91124/ai-extension-manager/actions/workflows/ci.yml)
- [](https://github.com/Jack91124/ai-extension-manager/releases/latest)
- 
- **Quick start** · [Why](#why-another-skill-manager) · [60-second workflow](#the-60-second-workflow) ·
- [Conflict model](#how-conflicts-work) · [Support matrix](#what-is-supported-today) ·
- [Safety](#safety-by-default) · [CLI](#cli-at-a-glance) · [Demo](demo/) · [Docs](#documentation)
- ---
- ## Why another skill manager?
- Every AI coding tool invented its own folder: `~/.claude/skills`, `~/.codex/skills`,
- `~/.gemini/skills`, `~/.cursor/skills`, `~/.copilot/skills`, `~/.dsh/skills`. In practice that means:
- - the same skill is copied five times, then edited in three places;
- - installing a skill for one tool leaves the other five behind;
- - a "sync" script copies files and silently deletes last week's local fix;
- - no one can answer "which tools have version 1.2 of this skill, and did any copy drift?"
- `aem` treats a **central library as the source of truth** and records exactly what was distributed
- to each tool. That record is what lets it distinguish "only the library changed" from "only the tool
- changed" from "both changed" — and refuse to guess in the last case.
- It is deliberately **local-first**: plain files, plain JSON, no server, no telemetry, no account.
- 
- <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>
- ## Quick start
- 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):
- ```bash
- 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:
- ```bash
- 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):
- ```bash
- 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:
- ```text
- $ 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
- ```
- ## The 60-second workflow
- ```bash
- # 1. bring a skill in from GitHub or a local folder
- aem import --source https://github.com/owner/repo/tree/main/skills/my-skill
- # 2. send it to the tools that need it (repeatable --agent)
- aem sync --direction distribute --agent claude --agent codex --resource my-skill
- # 3. prove the copies match the library
- aem verify --all
- aem status
- ```
- Everything is reversible: `aem backups` lists snapshots, `aem restore` brings back an old version,
- `aem compare` shows a unified diff between a library version, an old snapshot and a tool's copy.
- Want to edit a skill inside one tool and pull the change back? `aem sync --direction both` imports
- target-side changes that are safe, and stops with exit code `2` when both sides changed.
- ## How conflicts work
- Each resource stores a SHA-256 tree hash. Each target stores the hash it was synced from
- (`source_hash`), the hash it received (`target_hash`) and `synced_at`. From those three facts:
- | State | What happened | Default action |
- |---|---|---|
- | **A** | only the library changed | update the target (after a backup) |
- | **B** | only the target changed | keep the target, suggest importing it |
- | **C** | both sides changed | **conflict: write nothing, exit 2** |
- | **D** | the target was deleted | report missing, do not recreate silently |
- | **E** | the target directory does not exist | report unavailable, do not invent a path |
- | untracked | a copy exists that was never synced | identical → adopt; different → conflict |
- Conflicts are stored under `conflicts/` with the evidence (hashes, path, timestamp). Resolve them
- explicitly:
- ```bash
- aem compare --left resource:my-skill --right agent:claude:my-skill --diff
- aem sync --direction distribute --agent claude --resource my-skill --on-conflict library # keep library
- aem sync --direction import --agent claude --on-conflict new-version # keep target as a new version
- aem restore --resource my-skill --version <label> # roll back
- ```
- Nothing is overwritten by default — not on conflict, not on first contact with an untracked copy.
- The long version of this argument (why mtime is not a conflict policy, and what it costs to get it
- wrong) is in [docs/why-sync-overwrites.md](docs/why-sync-overwrites.md).
- ## What is supported today
- | Tool | Skills | Rules | MCP | Plugins | Verification |
- |---|---|---|---|---|---|
- | **Claude Code** | copy / link | `CLAUDE.md` | JSON merge | marketplace command | tested locally (CLI 2.1.318) |
- | **OpenAI Codex** | copy / link | `AGENTS.md` | manual (TOML) | marketplace command | config dir tested; CLI not installed |
- | **DSH** | copy / link | `AGENTS.md` | via plugins | `dsh plugin add` | tested locally (0.2.0-rc.2) |
- | **Gemini CLI** | copy / link | `GEMINI.md` | JSON merge | `gemini extensions install` | official docs; runtime not exercised |
- | **Cursor** | copy / link | `.cursor/rules` | JSON merge | marketplace UI only | paths partial (not installed) |
- | **VS Code / Copilot** | copy / link | instructions files | JSON merge | VS Code extensions | docs + local VS Code 1.115 |
- Plugin code is **never copied across tools**. A plugin is installed through its target tool's own
- mechanism; `aem` returns the exact command and refuses cross-tool moves for tool-specific plugins.
- ## Safety by default
- - **Scans before import** — dangerous shell patterns, risky scripts, secrets; high risk requires
- `--allow-risk`, credentials are refused (or rewritten to `${ENV_VAR}` placeholders for MCP).
- - **Backs up before overwriting** any target or library payload.
- - **Never deletes** another tool's resource without an explicit uninstall/restore command.
- - **Refuses git URL rewrites** that would redirect `github.com` to a third-party mirror
- (`--allow-mirror` to override).
- - **No secret exfiltration** — the library is local; `metadata/registry.json` stores hashes, not keys.
- - **Dry runs everywhere** — `--dry-run` shows the plan and leaves no journal behind.
- Read the full policy in [references/security-policy.md](references/security-policy.md).
- ## CLI at a glance
- | Command | What it does |
- |---|---|
- | `aem init` | create the library layout |
- | `aem doctor` | diagnose Python, paths, registry, schema, locks, tools, disk |
- | `aem status` | one table of every resource × tool, `--strict` fails on drift |
- | `aem scan` | detect tools, versions and skill folders |
- | `aem detect --path P` | classify P as skill / plugin / MCP / rules |
- | `aem import --source P` | import a local path or GitHub URL |
- | `aem sync --direction import\|distribute\|both` | two-way sync with conflict detection |
- | `aem adopt` | shortcut for import: pull every tool's new/changed resources in |
- | `aem distribute` | shortcut for distribute: push library resources to tools (backs up first) |
- | `aem compare --left A --right B --diff` | hash inventory + unified diff |
- | `aem verify --all` | verify installed copies against the library |
- | `aem backup` / `aem backups` / `aem restore` / `aem prune` | snapshots and rollback |
- Every command accepts `--home`, `--workspace` and `--json`. Exit codes: `0` success,
- `1` error, `2` conflict or difference. See [references/cli-reference.md](references/cli-reference.md).
- ## Demo
- The repository ships a self-contained demo that never touches your real tool folders:
- ```bash
- python demo/run_demo.py
- ```
- It creates a fake library and six fake tool homes, imports a skill, distributes it to three tools,
- verifies the hashes, edits one copy, shows the drift, edits the upstream copy, and ends with a real
- state-C conflict that it refuses to overwrite. The full captured transcript is in
- [demo/demo-output.txt](demo/demo-output.txt).
- ## Documentation
- | Document | Contents |
- |---|---|
- | [SKILL.md](SKILL.md) | the agent-facing skill: when to use it, decision rules, command recipes |
- | [references/architecture.md](references/architecture.md) | layers, data model, directory layout |
- | [references/resource-types.md](references/resource-types.md) | skill / plugin / MCP / rules compatibility |
- | [references/agent-compatibility.md](references/agent-compatibility.md) | per-tool paths and verification status |
- | [references/synchronization-engine.md](references/synchronization-engine.md) | import/distribute protocol, state machine |
- | [references/conflict-resolution.md](references/conflict-resolution.md) | A–E states and resolution playbook |
- | [references/security-policy.md](references/security-policy.md) | scanning, secrets, confirmations |
- | [references/installation-methods.md](references/installation-methods.md) | copy vs link vs tool-native install |
- | [references/dsh-plugin-spec.md](references/dsh-plugin-spec.md) | the planned GUI/execution plugin (not built) |
- | [docs/launch.md](docs/launch.md) | launch positioning, copy and channel checklist |
- | [docs/ROADMAP.md](docs/ROADMAP.md) | where this is going |
- ## Status and limits
- This is a working **v1.0 CLI + Agent Skill**, not a finished product:
- - ✅ import, distribute, both-way sync, conflict detection, backups, verify, compare, restore;
- - ✅ six adapters with honest verification levels, safety scanner, JSON contracts;
- - ✅ 25 scenario tests on disposable fake homes;
- - 🚧 DSH Plugin dashboard is **specified, not implemented** — no GUI is claimed here;
- - 🚧 plugin installation is delegated to each tool's native command (no auto-install yet);
- - ⚠️ Gemini CLI and Cursor were verified against official docs/path maps, not exercised at runtime;
- - ⚠️ Codex MCP writes are manual (TOML rewriting is intentionally not automated).
- ## Contributing
- Issues and pull requests are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) and
- [SECURITY.md](SECURITY.md). The scenario suite runs with plain Python:
- ```bash
- python evals/run_tests.py
- ```
- ## License
- MIT — see [LICENSE](LICENSE).
- Gitee mirror: <https://gitee.com/ping-pong-squid-king/ai-extension-manager.git>
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.