paperclipai/paperclip · error · Error

Skill not found: ${reference}

Error message

Skill not found: ${reference}

What it means

Thrown by resolveCompanySkillReference() as the final fallback: the reference matched no installed company skill by id, key, or (unique) slug. It means the skill is not installed in the current company, or the identifier is wrong. This is the normal 'no such skill' error for company-scoped skill operations.

Source

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

  const trimmed = reference.trim();
  if (!trimmed) {
    throw new Error("Skill reference is required.");
  }

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

  const byKey = skills.find((skill) => skill.key === trimmed);
  if (byKey) return byKey;

  const normalizedSlug = normalizeSkillSlug(trimmed);
  const bySlug = skills.filter((skill) => skill.slug === normalizedSlug);
  if (bySlug.length === 1 && bySlug[0]) return bySlug[0];
  if (bySlug.length > 1) {
    throw new Error(`Ambiguous skill slug "${trimmed}". Use a skill ID or key instead.`);
  }

  throw new Error(`Skill not found: ${reference}`);
}

async function resolveCompanySkill(
  ctx: ResolvedClientContext,
  reference: string,
): Promise<CompanySkillReferenceTarget> {
  return resolveCompanySkillReference(await listCompanySkills(ctx), reference);
}

async function checkCompanySkills(
  ctx: ResolvedClientContext,
  skillRef: string | undefined,
): Promise<CompanySkillCheckRow[]> {
  const skills = await listCompanySkills(ctx);
  const selected = skillRef ? [resolveCompanySkillReference(skills, skillRef)] : skills;
  const rows: CompanySkillCheckRow[] = [];
  for (const skill of selected) {
    const status = await ctx.api.get<CompanySkillUpdateStatus>(

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Run `paperclipai skills list` and copy the exact id/key.
2. If the skill exists only in the catalog, install it first with `skills install <catalogRef>`.
3. Confirm --company-id / PAPERCLIP_COMPANY_ID points at the company that actually has the skill.

Example fix

# before
paperclipai skills show codereview
# after
paperclipai skills install codereview   # if it is a catalog skill
paperclipai skills list                 # grab the installed id
paperclipai skills show <installed-id>

const installed = await runJson(["skills", "list", "--json"]);
const exists = installed.some(s => s.id === ref || s.key === ref || s.slug === normalizeSlug(ref));
if (!exists && !ref) throw new Error("Skill not installed; run `skills install` first.");

function skillExists(skills: Array<{id:string;key?:string;slug?:string}>, ref: string): boolean {
  return skills.some(s => s.id === ref || s.key === ref || s.slug === ref);
}

try {
  await run(["skills", "show", ref]);
} catch (err) {
  if (err instanceof Error && /Skill not found/.test(err.message)) {
    console.error("Not installed. Try `skills install " + ref + "`.");
    process.exit(2);
  }
  throw err;
}

When it happens

Trigger: Running `skills show|files|update|reset|remove|audit <ref>` or an agent sync with a ref that is not present among the company's installed skills. Also hit when using a catalog id before installing it.

Common situations: Forgetting to `skills install` a catalog skill first, targeting a skill from another company, stale cached id after a re-install, or simple typos.

Related errors

• Agent not found: ${agentRef}
• Catalog skill not found: ${catalogRef}
• Ambiguous skill slug "${trimmed}". Use a skill ID or key ins
• Agent not found: ${agentRef}
• Could not locate local Paperclip skills directory. Expected

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