Customer-readable description
What this skill can do
Synchronize an installed or local shared skill directory to a user-selected AI tool directory. It only creates or replaces symlinks with the same name; first use --dry-run to show the impact, then write once explicit authorization already exists.
How customers use it
Provide the source directory, target id or path, and an optional single skill name. The target is explicitly provided by --targets ; use an absolute path when no suitable built-in id exists.
python3 skills/soia-dev-sync-skills/scripts/sync_soia_skills.py \
--source-dir <shared-skill-dir> \
--targets codex,claude \
--dry-run
After confirming the plan, remove --dry-run. Use --skills <name> to sync only the specified skill; by default it also includes the dependencies.hard in its frontmatter;--no-deps can disable this behavior.
Dependencies and installation
npx skills add soia-team/soia-open-skills -g -a '*' -s soia-dev-sync-skills -y
Requires Python 3 and a source directory containing the SKILL.md subdirectory. An optional configuration example is in config.example.yml: it only records the user's own default source/targets, and command-line arguments take precedence. The configuration file is placed at:
~/.config/soia-skills/soia-open-skills/soia-dev/soia-dev-sync-skills/config.yml
SOIA_DEV_SYNC_SKILLS_CONFIG_FILE=<custom-config-path>
Logs and completion receipt
完成:<dry-run 或实际同步结果>。
日志摘要:
- source: <共享技能源>
- targets: <目标目录>
- linked/removed: <数量与名称>
- skipped/failed: <原因或无>
验证:<命令退出码、软链接解析或 dry-run>
问题与下一步:<确认、缺依赖或无>
Security boundaries
- First show the source, targets, and links to be created/replaced/removed; if there is no explicit write authorization for this round, stop at the preview.
- Refuse to use the source itself as a target; do not copy directories.
- Only handle
soia-*managed names and the currently named skill; never delete unrelated third-party skills. - By default, clean up first-level
soia-*symlinks that point to nonexistent targets; use--no-pruneto keep them.
Workflow
- Confirm
--source-dir, the targets, and the skill scope; do not guess personal directories or product workspaces. - Run
--dry-run, and review the create/replace/remove plan for each target. - After receiving authorization, execute the same command (without
--dry-run)。 - Review the exit code and the symlink resolution result for each target; report only what was actually verified.
Common commands:
# 查看内置目标或共享源中的技能
python3 skills/soia-dev-sync-skills/scripts/sync_soia_skills.py --list-targets
python3 skills/soia-dev-sync-skills/scripts/sync_soia_skills.py --source-dir <shared-skill-dir> --list-skills
# 同步一个技能并包含其 hard dependencies
python3 skills/soia-dev-sync-skills/scripts/sync_soia_skills.py \
--source-dir <shared-skill-dir> --targets <target-id-or-path> --skills <skill-name> --dry-run
Output files
The audit log is written to ${XDG_STATE_HOME:-~/.local/state}/soia-dev-sync-skills/, keeping at most 20. It records parameters, link changes, and a summary, and does not write secret contents.
Reference
references/targets-and-confirmation.md: built-in targets and confirmation rules.references/source-rules.md: resolution rules for local, GitHub, and skillsmp sources.references/soia-managed-skills.md: the naming boundary for restricted cleanup.
Verification
python3 skills/soia-dev-sync-skills/scripts/sync_soia_skills.py --list-targets
python3 -m py_compile skills/soia-dev-sync-skills/scripts/sync_soia_skills.py
Create a test skill containing only SKILL.md in a temporary directory, and run --dry-runagainst another temporary target; the acceptance output includes the expected create/link plan and the target directory is not written. Then run a non-dry-run once in an explicitly authorized test directory, and use readlink to verify that the link points to the source directory.