paperclipai/paperclip · error · Error

Skill reference is required unless --all is used.

Error message

Skill reference is required unless --all is used.

What it means

Thrown by requireSkillRef() inside the `skills update` action when neither `--all` nor a positional `[skillRef]` is supplied. The update command is the only caller: it must know whether to update one skill or all of them, and a bare `skills update` with no arguments and no flag is ambiguous.

Source

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

  }
}

function toSkillReferenceTarget(skill: CompanySkillReferenceTarget): CompanySkillReferenceTarget {
  return {
    id: skill.id,
    key: skill.key,
    slug: skill.slug,
    name: skill.name,
  };
}

function normalizeSkillSlug(value: string): string {
  return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
}

function requireSkillRef(skillRef: string | undefined): string {
  if (!skillRef?.trim()) {
    throw new Error("Skill reference is required unless --all is used.");
  }
  return skillRef;
}

function collectOptionValue(value: string, previous: string[]): string[] {
  return [...previous, value];
}

function emptyToUndefined(values: string[] | undefined): string[] | undefined {
  return values && values.length > 0 ? values : undefined;
}

function appendQueryParam(params: URLSearchParams, key: string, value: string | undefined): void {
  const trimmed = value?.trim();
  if (trimmed) {
    params.set(key, trimmed);
  }
}

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Pass a specific skill: `paperclipai skills update <skillRef>`.
2. Or update all skills: `paperclipai skills update --all`.
3. Do not combine both — the command also rejects `--all` together with a skillRef.

Example fix

# before
paperclipai skills update
# after
paperclipai skills update --all
# or
paperclipai skills update my-skill

const args = ["skills", "update"];
if (all) args.push("--all");
else if (skillRef && skillRef.trim()) args.push(skillRef);
else throw new Error("Pass a skillRef or --all to skills update.");
await run(args);

function hasUpdateTarget(all: boolean, ref?: string): boolean {
  return all || Boolean(ref?.trim());
}

When it happens

Trigger: Running `paperclipai skills update` with no positional argument and without `--all`. Also if the positional is whitespace-only (trim yields empty).

Common situations: Forgetting `--all` in automation, or assuming `skills update` updates everything by default.

Related errors

• --file is required
• Challenge secret is required. Pass --token or --token-env.
• Cannot build API path with an empty path segment.
• Invalid --include value. Use one or more of: company,agents,
• Use either a skill reference or --all, not both.

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