What causes "set agent skills: %w" in multica-ai/multica?

List valid skills (`multica skill list` or equivalent) and verify every id before setting

set agent skills: %w

Error message

set agent skills: %w

What it means

Wrapped error returned when `multica agent skills set <id>` fails to PUT {"skill_ids": [...]} to `/api/agents/{id}/skills`. The server validates ids and state; the wrapped cause is typically 404 (agent or one of the skill ids unknown), 401/403 (auth), or a connection failure. Because this is a full replacement, the server rejects the whole batch if any id is invalid.

Source

Thrown at server/cmd/multica/cmd_agent.go:1039

	client, err := newAPIClient(cmd)
	if err != nil {
		return err
	}

	if !cmd.Flags().Changed("skill-ids") {
		return fmt.Errorf("--skill-ids is required (comma-separated skill IDs; use --skill-ids '' to clear all)")
	}
	cleanIDs := cleanSkillIDsFlag(cmd)
	body := map[string]any{
		"skill_ids": cleanIDs,
	}

	ctx, cancel := cli.APIContext(context.Background())
	defer cancel()

	var result json.RawMessage
	if err := client.PutJSON(ctx, "/api/agents/"+args[0]+"/skills", body, &result); err != nil {
		return fmt.Errorf("set agent skills: %w", err)
	}

	return printAgentSkillsMutationResult(cmd, args[0], result)
}

func runAgentSkillsAdd(cmd *cobra.Command, args []string) error {
	client, err := newAPIClient(cmd)
	if err != nil {
		return err
	}

	if !cmd.Flags().Changed("skill-ids") {
		return fmt.Errorf("--skill-ids is required (comma-separated skill IDs)")
	}
	cleanIDs := cleanSkillIDsFlag(cmd)
	if len(cleanIDs) == 0 {
		return fmt.Errorf("--skill-ids must include at least one skill ID")
	}

View on GitHub (pinned to 2c0912b6ec)

Solutions

List valid skills (`multica skill list` or equivalent) and verify every id before setting
Confirm the agent id via `multica agent list`
Fix connectivity/auth if the wrapped error is connection or 401/403 class
Re-run with only confirmed-existing skill ids

Example fix

# before
multica agent skills set agt_1 --skill-ids sk_old,sk_typo
# Error: set agent skills: 400: unknown skill id sk_typo

# after
multica skill list
multica agent skills set agt_1 --skill-ids sk_new,sk_valid

Defensive patterns

Strategy: try-catch

Validate before calling

multica skill list --output json | jq -e --arg id "$SKILL_ID" '.[] | select(.id == $id)' >/dev/null || { echo 'unknown skill id'; exit 1; }
multica agent skills set "$AGENT_ID" --skill-ids "$SKILL_IDS"

Try / catch

if err := client.PutJSON(ctx, "/api/agents/"+args[0]+"/skills", body, &result); err != nil {
	return fmt.Errorf("set agent skills: %w", err) // 400 names the offending skill id
}

Prevention

Verify every skill id against the skill list before setting
Remember set replaces the whole list — validate all ids, not just new ones
Refresh id lists after skills are recreated

When it happens

Trigger: Including a deleted or mistyped skill id in the comma list, targeting a nonexistent agent, expired token, or server unreachable.

Common situations: Skill ids copied from another workspace or after skills were re-created with new ids; trailing whitespace is trimmed by cleanSkillIDsFlag but case-mangled or truncated ids are not; stale tokens in CI jobs.

Related errors

AI-assisted analysis of multica-ai/multica@2c0912b6ec (2026-08-15). Data as JSON: /api/errors/56506561618de827. Report an issue: GitHub.