SuperAPI AI Directory

soia-dev-sync-skills

General & other

View repository

Updated 10-16 08:49

About this skill

soia-dev-sync-skills

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-prune to keep them.

Workflow

  1. Confirm --source-dir, the targets, and the skill scope; do not guess personal directories or product workspaces.
  2. Run --dry-run, and review the create/replace/remove plan for each target.
  3. After receiving authorization, execute the same command (without --dry-run)。
  4. 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.