multica-skill-update

Multica Skill Sync Tool

Batch import/update the skills in a **maintainable source manifest (scripts/manifest.local.json)** to the Multica workspace skill database, turning "install/update a batch of skills" into a single command or a scheduled task.

When to use

• You (or Orion / Autopilot) need to install multiple skills into Multica from external sources, and the sources will be updated.
• Manually doing it one by one import is prone to omissions and forgotten versions—use this skill to batch-execute according to the manifest.
• Need to periodically refresh (scheduled weekly) the skills in Multica to the latest versions.

Core principles (must be followed)

1. Sync target = Multica skill database, not the local .codebuddy/skills/ path. The local path is issued by the platform; changing it will not let the agent read it, and it is also easily overwritten.
2. This skill is only responsible for "how to do it"(logic/manifest format/steps), not "when to run it"—scheduling is triggered by the Multica Autopilot CRON.
3. Source refresh must go through import --on-conflict overwrite, not multica skill update(see "Key clarification" below).
4. The manifest is entered by the maintainer: write the source URL into the skill's internal scripts/manifest.local.json and then install it back into Multica.

File structure

multica-skill-update/
├── SKILL.md                      # 本入口文档
├── references/
│   ├── manifest-format.md        # 清单格式、字段说明、分类标签用法
│   ├── multica-importing-alignment.md  # 与平台内置 skill 的分工 + 8 条语义对齐 + 排除/媒体剔除
│   └── workflow-examples.md      # 真实调用示例 + 反向溯源工作流
└── scripts/
    ├── sync_skills.py            # init/update/plan 三模式执行脚本
    ├── manifest.example.json     # 清单模板（复制后填入真实来源；入库）
    └── manifest.local.json       # 个人来源清单（你维护，含本地文件路径/云端地址；由外部仓库统一决定是否入库）

Personal manifest mechanism：scripts/manifest.local.json is your private sync manifest—you can enterlocal skill files（source: "file"，url write the local path), or entercloud skill addresses（source: "github" | "clawhub" | "skills.sh"，url write the corresponding URL). It is placed together with the template scripts/manifest.example.json , and the only difference is whether a real source has been filled in;scripts/manifest.example.json is the entry template, for copying and filling in. First use:

cp scripts/manifest.example.json scripts/manifest.local.json
# 编辑 scripts/manifest.local.json：本地 skill 用 source=file + 本机路径；云端用 source=github/clawhub/skills.sh + URL

For the complete fields and values of the manifest, see references/manifest-format.md。

Dependencies

System dependencies

Dependency	Installation method
multica CLI	Standalone installation: macOS/Linux: curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash or brew install multica-ai/tap/multicaWindows: irm https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.ps1 | iexVerification:multica version

Actual available CLI path (tested on this machine): The Multica desktop App already includes a standalone CLI binary, no separate installation is needed:

# App 内置 CLI（Go 二进制，v0.4.19+）
MULTICA_BIN="/Applications/Multica.app/Contents/Resources/app.asar.unpacked/resources/bin/multica"
"$MULTICA_BIN" version        # → multica v0.4.19 ...

# 该 CLI 需要指定 App 使用的 profile 才能连上 daemon/server
"$MULTICA_BIN" --profile desktop-api.multica.ai workspace list --output json

• Prerequisite: The Multica desktop App / daemon is already running (the CLI communicates with the server/daemon).
• profile: The profile name usually used when the App runs automatically is desktop-api.multica.ai(corresponding to ~/.multica/profiles/<name>/config.json); the CLI defaulting to the default profile will report No server configured. Run 'multica setup' first., in which case you need to explicitly add --profile。
• workspace：skill list and other commands require --workspace-id or --workspace-slug；multica --profile <p> workspace list --output json to check.
• The script already performs a pre-check:multica when not in PATH, it outputs installation instructions and exits with code 2; for actual invocation you can use --multica-bin to point to the App's built-in path.

Usage steps

1. Prepare the manifest

scripts/manifest.local.json is the personal manifest. On first use, copy the template and fill in the real sources:

cp scripts/manifest.example.json scripts/manifest.local.json
# 编辑 scripts/manifest.local.json：本地 skill 用 source=file + 本机路径；云端用 source=github/clawhub/skills.sh + URL

For field syntax and classification tag usage, see references/manifest-format.md。

2. Execute the sync

# 初始化导入（同名已存在视为正常，不报错）
python scripts/sync_skills.py --mode init

# 更新刷新（on_conflict 按清单策略：overwrite 刷新 / skip 跳过非本人）
python scripts/sync_skills.py --mode update

# 预览将执行的操作，不实际调用 import
python scripts/sync_skills.py --mode plan

# 按分类筛选：只导入某类 skill（便于针对某个 agent 配置）
python scripts/sync_skills.py --mode init  --category legal-document
python scripts/sync_skills.py --mode update --category development

# 指定清单路径 / dry-run 只打印命令
python scripts/sync_skills.py --manifest scripts/manifest.local.json --mode init
python scripts/sync_skills.py --dry-run

Connection parameters (required as tested on this machine): When using the CLI built into the Multica desktop App, you usually need to explicitly specify the profile and workspace:

# 先查 workspace（用 App 的 profile）
MULTICA="/Applications/Multica.app/Contents/Resources/app.asar.unpacked/resources/bin/multica"
"$MULTICA" --profile desktop-api.multica.ai workspace list --output json
# → [{"id": "...", "name": "xierluo", "slug": "xierluo"}]

# 同步时带上 profile + workspace-id
python scripts/sync_skills.py --mode update \
  --profile desktop-api.multica.ai \
  --workspace-id <workspace-id>

• The script automatically detects the multica CLI (PATH → built into the App); you can also use --multica-bin /path/to/multica to specify it explicitly.
• When no profile is specified, it defaults to default, which may report No server configured——use --profile desktop-api.multica.ai(corresponds to the App runtime profile, see ~/.multica/profiles/）。
• For a complete example, see references/workflow-examples.md。

3. View the report

Each run outputs a structured summary:

=== 同步报告 ===
imported: 3 (created 1, updated 2)
conflict(existed): 1
skipped: 1 (not creator 1, disabled 0)
failed: 0

• imported: successfully imported (created=new, updated=overwrite refresh)
• conflict(existed): an item with the same name already exists, skipped according to the policy
• skipped：not creator(overwrite/skip not created by yourself are skipped) + disabled（enabled=false）
• failed: genuine failures (invalid URL, illegal policy, etc.)——the exit code is non-zero when there are failures, making it easy for Autopilot/CI to detect

Division of labor with the platform's built-in skill (key points)

This skill and the platform's built-in multica-skill-importing are in an upstream/downstream relationship: it is responsible for the authoritative semantics of a single import, and this skill strictly reuses the same set of semantics for batch orchestration. For the complete comparison table and the 8 semantic alignments (including server-side hard limits, reserved filenames, zip layout, and media removal), see references/multica-importing-alignment.md。

Key clarifications (already written into the implementation, do not confuse them again)

• multica skill update <id> ≠ re-pulling from the source. It only edits the fields (name/description/content/config) of an existing skill by ID,it will not pull the latest from GitHub. So the "sync source" step always uses import --on-conflict overwrite, not skill update。
• import 's --url and --file are mutually exclusive; if the source is on GitHub / ClawHub / skills.sh, use --url。
• overwrite is limited to the original creatorto execute; non-creators will fail. In the manifest, use skipfor sources not created by yourself, to avoid failed noise.
• --on-conflict defaults to fail: on a same-name conflict, stop and do not modify the existing content. Entries in the manifest that do not specify a policy are handled as fail (will be reported as failed).
• --output json is the recommended format for scripting/parsing (the official documentation explicitly states "scripts should use JSON output rather than parse tables").

Scheduled refresh (Multica Autopilot integration)

Autopilot handles "scheduling", and this skill handles "how to do it". Create an autopilot with a weekly CRON, and dispatch an agent to call this skill with mode=update :

# 创建 autopilot（--mode create_issue：先建 issue 再派发给 agent）
multica autopilot create --title "Weekly skill sync" \
  --agent <agent-name> --mode create_issue --output json

# 添加每周一 9:00（Asia/Shanghai）的定时触发器
multica autopilot trigger-add <autopilot-id> \
  --kind schedule --cron "0 9 * * 1" --timezone Asia/Shanghai --output json

• Manual trigger:multica autopilot trigger <autopilot-id>
• View run history:multica autopilot runs <autopilot-id>
• cron has 5 fields (minute hour day month weekday, no seconds), and the time zone uses an IANA name.
• Execution mode recommend create_issue: after the agent finishes running, the result stays on the issue, making it easy to review;run only results are only in the run history.

⚠️ Note:autopilot create 's actual flags are subject to the local multica autopilot create --help (the documentation marks --title --agent --mode as required, and there are also --priority --project --subscriber）；trigger-add flags that you should also first --help confirm.

Acceptance criteria

1. After the skill is installed,multica skill list you can see multica-skill-update。
2. Use init mode, with a manifest containing ≥2 sources, and it can be imported successfully (or correctly report that it already exists).
3. After modifying the source content, use update mode to refresh to the latest (report updated）。
4. Skills not created by yourself are handled according to skip The strategy is skipped, producing no failed noise.
5. After connecting to the weekly Autopilot, it can synchronize periodically without manual intervention.