{"record":{"id":"8ef3ac1b4345aac5","repo":"paperclipai/paperclip","slug":"at-least-one-skill-value-is-required-for-skills","errorCode":null,"errorMessage":"At least one --skill value is required for skills agent sync.","messagePattern":"At least one --skill value is required for skills agent sync\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"cli/src/commands/client/skills.ts","lineNumber":519,"sourceCode":"      }),\n    { includeCompany: true },\n  );\n\n  addCommonClientOptions(\n    agent\n      .command(\"sync\")\n      .description(\"Merge an agent's desired company skills and sync runtime state\")\n      .argument(\"<agentRef>\", \"Agent ID or shortname/url-key\")\n      .option(\"--skill <skillRef>\", \"Desired company skill ID, key, or slug; may be repeated\", collectOptionValue, [] as string[])\n      .requiredOption(\n        \"--mode <mode>\",\n        \"Merge mode: add keeps other skills; remove deletes only named skills; replace destructively overwrites the complete set\",\n      )\n      .action(async (agentRef: string, opts: AgentSkillSyncOptions) => {\n        try {\n          const desiredSkills = opts.skill ?? [];\n          if (desiredSkills.length === 0) {\n            throw new Error(\"At least one --skill value is required for skills agent sync.\");\n          }\n          const ctx = resolveCommandContext(opts, { requireCompany: true });\n          const agentRow = await resolveAgent(ctx, agentRef);\n          const mode = agentSkillAssignmentModeSchema.parse(opts.mode);\n          const snapshot = await ctx.api.post<AgentSkillSnapshot>(\n            `/api/agents/${encodeURIComponent(agentRow.id)}/skills/sync`,\n            { desiredSkills, mode },\n          );\n          if (ctx.json) {\n            printOutput(snapshot, { json: true });\n            return;\n          }\n          console.log(\n            `Desired company skills updated with ${mode} mode for ${agentRow.name} (${agentRow.id}); runtime sync returned ${snapshot?.entries.length ?? 0} entrie(s).`,\n          );\n          printAgentSkillSnapshot(snapshot, agentRow);\n        } catch (err) {\n          handleCommandError(err);","sourceCodeStart":501,"sourceCodeEnd":537,"githubUrl":"https://github.com/paperclipai/paperclip/blob/67001ec6eb96ae601aa27bc91d9b2415d665334a/cli/src/commands/client/skills.ts#L501-L537","documentation":"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.","triggerScenarios":"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 `[]`).","commonSituations":"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.","solutions":["Add at least one `--skill <ref>`: `skills sync <agent> --mode add --skill skill-a --skill skill-b`","In scripts, build the flag array and fail fast if it is empty before invoking the command","Confirm the skill refs exist with `paperclipai skills list -C <companyId>` first"],"exampleFix":"# before\npaperclipai skills sync agent-1 --mode replace\n# after\npaperclipai skills sync agent-1 --mode replace --skill skill-a --skill skill-b","handlingStrategy":"validation","validationCode":"function requireSkills(skills: string[]): string[] {\n  const trimmed = skills.map((s) => s.trim()).filter(Boolean);\n  if (trimmed.length === 0) {\n    throw new Error(\"At least one --skill value is required for skills agent sync.\");\n  }\n  return trimmed;\n}\nconst desired = requireSkills(opts.skill ?? []);","typeGuard":"function hasSkills(v: unknown): v is string[] {\n  return Array.isArray(v) && v.every((s) => typeof s === \"string\") && v.some((s) => s.trim().length > 0);\n}","tryCatchPattern":null,"preventionTips":["Build the --skill list in a variable and fail fast if empty","Confirm skill refs exist with `skills list` first","Remember --skill can be repeated to supply multiple refs"],"tags":["cli","skills","validation","required-input","agent"],"backgroundTag":null,"analyzedSha":"67001ec6eb96ae601aa27bc91d9b2415d665334a","analyzedAt":"2026-08-12T12:05:45.408Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}