paperclipai/paperclip · error · Error

Catalog skill reference is required.

Error message

Catalog skill reference is required.

What it means

Thrown by getCatalogSkill() in the skills CLI client when the catalog skill reference argument is empty after trimming. The function guards its call to GET /api/skills/catalog/ref?ref=... because an empty ref would produce a meaningless API request. It is a pure client-side input guard, reached before any network call.

Source

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

  return (await ctx.api.get<CompanySkillListItem[]>(`/api/companies/${ctx.companyId}/skills`)) ?? [];
}

async function listCatalogSkills(
  ctx: ResolvedClientContext,
  opts: CatalogBrowseOptions,
): Promise<CatalogSkill[]> {
  const params = new URLSearchParams();
  appendQueryParam(params, "kind", opts.kind);
  appendQueryParam(params, "category", opts.category);
  appendQueryParam(params, "q", opts.query);
  const query = params.toString();
  return (await ctx.api.get<CatalogSkill[]>(`/api/skills/catalog${query ? `?${query}` : ""}`)) ?? [];
}

async function getCatalogSkill(ctx: ResolvedClientContext, catalogRef: string): Promise<CatalogSkill> {
  const ref = catalogRef.trim();
  if (!ref) {
    throw new Error("Catalog skill reference is required.");
  }
  const detail = await ctx.api.get<CatalogSkill>(`/api/skills/catalog/ref?ref=${encodeURIComponent(ref)}`);
  if (!detail) {
    throw new Error(`Catalog skill not found: ${catalogRef}`);
  }
  return detail;
}

export function resolveCompanySkillReference(
  skills: CompanySkillReferenceTarget[],
  reference: string,
): CompanySkillReferenceTarget {
  const trimmed = reference.trim();
  if (!trimmed) {
    throw new Error("Skill reference is required.");
  }

  const byId = skills.find((skill) => skill.id === trimmed);

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Pass a non-empty catalog skill ID, key, or unique slug to `skills inspect`.
2. If the ref comes from a variable, validate it is non-empty before invoking the CLI.
3. List valid refs first with `paperclipai skills browse` and pick one.

Example fix

// before
const ref = process.env.SKILL_REF ?? "";
await run(["skills", "inspect", ref]);
// after
const ref = (process.env.SKILL_REF ?? "").trim();
if (!ref) throw new Error("SKILL_REF must be set");
await run(["skills", "inspect", ref]);

const ref = (catalogRef ?? "").trim();
if (!ref) {
  throw new Error("Provide a non-empty catalog skill id, key, or slug.");
}
await cli(["skills", "inspect", ref]);

function isValidCatalogRef(ref: string | undefined): ref is string {
  return typeof ref === "string" && ref.trim().length > 0;
}

When it happens

Trigger: Running `paperclipai skills inspect <catalogRef>` (or any path calling getCatalogSkill) with a reference that is an empty string or only whitespace, e.g. `paperclipai skills inspect " "`. The commander `<catalogRef>` argument is required, so this only fires when the value is present-but-blank.

Common situations: Shell expansion that yields an empty variable (e.g. `paperclipai skills inspect "$MY_REF"` where MY_REF is unset/blank), script loops passing untrimmed input, or copy-paste mistakes.

Related errors

• Skill reference is required.
• Catalog team reference is required.
• Prompt text is required
• Agent reference is required
• Invalid --include value. Use one or more of: company,agents,

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