SuperAPI AI Directory

soia-env-open-skills-install

General & other

View repository

Updated 10-16 08:46

About this skill

soia-env-open-skills-install

Get the SOIA open-source skills installed, or update an existing installation to the latest version. Supports three granularities × any host combination, covering everything from "full initial install" to "single skill upgrade" with one command.

Division of labor with soia-meta-skill-release : this skill targetsinstallation/update from the user's perspective; skill-release targetssha pin refresh, old name cleanup, and lock reconciliation after a maintainer release. The WorkBuddy script is shared by both, but is invoked at different times.

Customer-readable description

What this skill can do

What the customer wants What the skill does What the customer can see
Install all SOIA skills / plugins in full Connect to the marketplace → install all 8 domain plugins → three hosts Per-host install plan and domain-level receipts
Install all SOIA skills on a specified host Operate only on the target host, skip the rest Single-host domain-level receipts
Install or update a certain domain plugin (e.g. soia-dev) plugin install / plugin update that domain Before/after version comparison for that domain across hosts
Update a single skill under a certain domain plugin Update the entire plugin (skills are delivered as a plugin unit) + state which skill was updated Plugin-level update + skill change description
Check the current installation status without modifying the machine List the marketplace status for each host and the installed plugin versions Three-host three-column status table

Granularity explanation: SOIA uses "domain plugin" as the minimum delivery unit (e.g. soia-dev@soia contains 9 skills). "Updating a single skill" in plugin mode is equivalent to updating the entire domain plugin, but the skill will state which skill triggered the update. If you need to truly install at skill granularity (without installing other skills in the same domain), you must switch to the npx skills add route — the skill will indicate that this route and the plugin route are mutually exclusive, and let the customer choose.

How the customer uses it (natural language examples)

What the customer says The skill's understanding Execution scope
"Help me install all SOIA skills" Full install, all hosts 8 domains × 3 hosts
"Help me install all SOIA plugins" Full install, all hosts 8 domains × 3 hosts
"Help me install all SOIA skills under Codex" Full install, Codex host 8 domains × Codex
"Help me install all SOIA plugins under Codex" Full install, Codex host 8 domains × Codex
"Help me install all SOIA skills under Claude Code" Full install, Claude Code host 8 domains × Claude Code
"Help me update all SOIA plugins under Claude Code" Full update, Claude Code host 8 domains × Claude Code
"Help me update the soia-dev plugin under Claude Code" Single-domain update, Claude Code host soia-dev × Claude Code
"Help me update the soia-dev-coding-agent skill in soia-dev under Claude Code" Single-skill trigger, update the entire plugin soia-dev × Claude Code
"Help me install all SOIA experts in WorkBuddy" Full installation, WorkBuddy host 8 domains × WorkBuddy
"Only check the current status, do not install" Read-only check Check all 3 hosts, make no changes

Before performing any installation/update, display the plan and wait for customer confirmation; do not modify the machine without explicit consent.

8 open-source domain plugins

Plugin name Domain repo Skill count Resident cost
soia-meta soia-open-skills 4 ~428 tok
soia-dev soia-open-dev-skills 9 —
soia-dev-design soia-open-dev-design-skills 5 —
soia-pkm-vault soia-open-pkm-vault-skills 15 —
soia-media-content soia-open-media-content-skills 6 ~728 tok
soia-cwork-office soia-open-cwork-office-skills 3 —
soia-env soia-open-env-skills 15 —
soia-edu-course soia-open-edu-course-skills — —

Dependencies and installation

Dependency Type What to do when missing
claude CLI By host Skip the Claude host, suggest calling soia-env-claude-cli-install
codex CLI By host Skip the Codex host, suggest calling soia-env-codex-install
WorkBuddy By host Skip WorkBuddy, suggest calling soia-env-workbuddy-install
Python 3 WorkBuddy steps Skip WorkBuddy expert installation and explain
soia-meta-skill-release script WorkBuddy steps Skip WorkBuddy expert installation and provide path instructions
Network diagnostics Optional prerequisite When marketplace onboarding fails, call soia-env-network-diagnose

This skill is soia-env-environment-setup 's downstream (the next step after the environment is ready), and can also be triggered independently.

Standard procedure

Install the entire domain (Claude Code and Codex share the same domain plugin):

claude plugin marketplace add soia-team/soia-open-skills
claude plugin install soia-env@soia

Install only this one skill:

npx skills add soia-team/soia-open-env-skills -g -a '*' -s soia-env-open-skills-install -y

Phase 0 · Check (read-only, do not modify the machine)

python3 scripts/inspect_soia_plugins.py --json

Output the availability of each host, marketplace onboarding status, and installed plugin versions.

Phase 1 · Confirm the installation plan

Based on customer intent, calculate the installation/update matrix of target hosts × target domains, display it, and wait for customer confirmation. Decision rules:

  • Host: when no host is specified, detect all available hosts; when "Codex", "Claude Code", or "WorkBuddy" is specified, operate only on that host.
  • Granularity: "all SOIA skills/plugins" → all 8 domains; "soia-dev" → single domain; "a certain skill" → find its domain → single domain.
  • Action: plugin not installed → install; already installed → update (and display the current version and latest version).

Phase 2 · Claude Code installation/update

# 市场未接入时先接入
claude plugin marketplace add soia-team/soia-open-skills

# 未安装的域:install
claude plugin install <域名>@soia

# 已安装的域:update
claude plugin update <域名>@soia

Execute domain by domain; if any domain fails, record it and continue; after each domain is complete, use plugin list to verify the version.

Phase 3 · Codex installation/update

# 市场暂存必须刷新,否则拿到旧缓存(已知约束:2026-07-27 实际踩过)
rm -rf ~/.codex/.tmp/marketplaces/soia
codex plugin marketplace add soia-team/soia-open-skills

# 未安装的域:add
codex plugin add <域名>@soia

# 已安装的域:remove + add(Codex 无 update 命令)
codex plugin remove <域名>@soia
codex plugin add <域名>@soia

Phase 4 · WorkBuddy expert installation/update

# dry-run 先看计划
python3 <soia-open-skills>/skills/soia-meta-skill-release/scripts/install_workbuddy_experts.py \
  --dry-run [<域名>]

# 确认后执行(无参数装全部,传域名只装指定域)
python3 <soia-open-skills>/skills/soia-meta-skill-release/scripts/install_workbuddy_experts.py \
  [<域名>]

After completion, you must prompt the customer torestart WorkBuddy, otherwise the new experts will not appear.<soia-open-skills> The path is resolved via the SOIA_SKILL_REPOS_ROOT environment variable or the --repo-dir parameter; if neither is present, prompt the customer to specify the path.

Phase 5 · Final verification

python3 scripts/inspect_soia_plugins.py --json

Compare the state before and after installation, and output a domain-level receipt table.

Status receipt (mandatory)

After installation/update completes, output the following table, one row per target domain:

Domain Claude Code Codex WorkBuddy Update time Notes
soia-meta Installed 1.8.0 Installed 1.8.0 — 2026-08-01T10:00:00+08:00 WorkBuddy has no expert for this domain
soia-dev Installed 1.6.0 Skipped (host unavailable) Installed 2026-08-01T10:00:01+08:00 —
  • Host unavailable: write "Skipped (host unavailable)", do not write "Failed"
  • Existing version unchanged: write "Already latest <version>"
  • First install: write "Installed <version>"
  • Update: write "Updated <old version> → <new version>"
  • 更新时间 Generated in real time after final verification in this domain, format RFC3339 with time zone

About the "single skill" granularity

In plugin mode, skills are delivered asdomain pluginsas the delivery unit; installing only a single skill within a domain is not supported:

  • Customer wants to "update soia-dev-coding-agent in soia-dev" → update the entire soia-dev plugin → all 9 skills are upgraded
  • If the customer really only needs that single skill (and does not want the other 8 in the same domain) → inform them they need to switch to the npx skills add route, but the npx route and the plugin route aremutually exclusive(coexistence creates two indexes that drift independently) → have the customer make an explicit choice

What it does not cover

  • Uninstall and disable. When the customer wants to uninstall or disable a plugin, provide the claude plugin uninstall/disable <域名>@soia、codex plugin remove <域名>@soia command instructions and let the customer decide; this skill does not actively perform uninstallation.
  • Private skill repositories. It only covers the open-source marketplace soia-team/soia-open-skills 's 8 domain plugins; onboarding private skill repositories is out of scope, and this repository does not mention their installation method.
  • Release wrap-up. sha pin refresh, old name cleanup, and lock reconciliation are maintainer actions handled by soia-meta-skill-release ; when the customer says "release skill", route it there.

Intermediate state of installation and update

When modifying a machine, display the stage list; on failure, stop the current host (without affecting other hosts):

checking → planning/waiting_confirmation → installing/updating → verifying → completed/failed/blocked

Permissions and rollback

  • claude plugin and codex plugin commands are both user-level operations and do not require administrator privileges
  • WorkBuddy script writes to ~/.workbuddy/plugins/marketplaces/my-experts/plugins, no administrator privileges required
  • On failure, no automatic rollback; provide the corresponding manual uninstall command for the customer to choose

Private information and intermediate data

  • Does not read or store any credentials
  • Read-only checks are not written to disk; during installation, desensitized progress is written to ~/.local/state/soia-skills/soia-env-open-skills-install/
  • Does not write local paths or usernames into the repository

Logging and completion receipt

Final output: host availability list + domain installation receipt table + retryable commands for failed domains + WorkBuddy restart prompt (if any).

Forward testing

  • Mock claude/codex: scenarios of not installed / installed without marketplace / marketplace already onboarded
  • Verify that "skip unavailable host" does not affect other hosts
  • Verify that "specify a single host" operates only on that host
  • Verify that "specify a single domain" installs/updates only that domain
  • Verify that "already latest" does not trigger repeated installation (when update output is already at latest, record "Already latest")
  • Verify that "single skill trigger" finds the owning domain and updates the entire plugin
  • Verify that when the WorkBuddy script path is missing, a clear prompt is given rather than an abnormal exit
  • Verify 更新时间 is generated after verification, not hardcoded