paperclipai/paperclip · error · Error

At least one --skill value is required for skills agent sync

Error message

At least one --skill value is required for skills agent sync.

What it means

The `skills sync` command merges an agent's desired company-skill set. It collects repeated `--skill <ref>` values via `collectOptionValue` into an array and requires at least one entry before resolving the agent or calling `/api/agents/<id>/skills/sync`. An empty array throws immediately. The `--mode` option is required (Commander `requiredOption`) but is not the cause of this error.

Source

Thrown at cli/src/commands/client/skills.ts:519

      }),
    { includeCompany: true },
  );

  addCommonClientOptions(
    agent
      .command("sync")
      .description("Merge an agent's desired company skills and sync runtime state")
      .argument("<agentRef>", "Agent ID or shortname/url-key")
      .option("--skill <skillRef>", "Desired company skill ID, key, or slug; may be repeated", collectOptionValue, [] as string[])
      .requiredOption(
        "--mode <mode>",
        "Merge mode: add keeps other skills; remove deletes only named skills; replace destructively overwrites the complete set",
      )
      .action(async (agentRef: string, opts: AgentSkillSyncOptions) => {
        try {
          const desiredSkills = opts.skill ?? [];
          if (desiredSkills.length === 0) {
            throw new Error("At least one --skill value is required for skills agent sync.");
          }
          const ctx = resolveCommandContext(opts, { requireCompany: true });
          const agentRow = await resolveAgent(ctx, agentRef);
          const mode = agentSkillAssignmentModeSchema.parse(opts.mode);
          const snapshot = await ctx.api.post<AgentSkillSnapshot>(
            `/api/agents/${encodeURIComponent(agentRow.id)}/skills/sync`,
            { desiredSkills, mode },
          );
          if (ctx.json) {
            printOutput(snapshot, { json: true });
            return;
          }
          console.log(
            `Desired company skills updated with ${mode} mode for ${agentRow.name} (${agentRow.id}); runtime sync returned ${snapshot?.entries.length ?? 0} entrie(s).`,
          );
          printAgentSkillSnapshot(snapshot, agentRow);
        } catch (err) {
          handleCommandError(err);

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Add at least one `--skill <ref>`: `skills sync <agent> --mode add --skill skill-a --skill skill-b`
2. In scripts, build the flag array and fail fast if it is empty before invoking the command
3. Confirm the skill refs exist with `paperclipai skills list -C <companyId>` first

Example fix

# before
paperclipai skills sync agent-1 --mode replace
# after
paperclipai skills sync agent-1 --mode replace --skill skill-a --skill skill-b

function requireSkills(skills: string[]): string[] {
  const trimmed = skills.map((s) => s.trim()).filter(Boolean);
  if (trimmed.length === 0) {
    throw new Error("At least one --skill value is required for skills agent sync.");
  }
  return trimmed;
}
const desired = requireSkills(opts.skill ?? []);

function hasSkills(v: unknown): v is string[] {
  return Array.isArray(v) && v.every((s) => typeof s === "string") && v.some((s) => s.trim().length > 0);
}

When it happens

Trigger: Running `paperclipai skills sync <agentRef> --mode add` with no `--skill` values; passing `--skill ""` which contributes an empty string but still length 1 (that would NOT trigger this — only truly omitting all `--skill` flags triggers it, since the default is `[]`).

Common situations: Forgetting the `--skill` flags; a script building the `--skill` list from a variable that expanded to nothing; misunderstanding that sync needs an explicit desired set.

Related errors

• --payload must be a JSON object
• Agent not found: ${agentRef}
• Agent reference is required
• Agent key belongs to ${agent.name} (${agent.id}), not '${ref
• Secret value is required. Pass --value or --value-env.

AI-assisted analysis of paperclipai/paperclip@67001ec6eb (2026-08-12). Data as JSON: /api/errors/8ef3ac1b4345aac5. Report an issue: GitHub.