paperclipai/paperclip · error · Error

Could not locate local Paperclip skills directory. Expected

Error message

Could not locate local Paperclip skills directory. Expected ./skills in the repo checkout.

What it means

Thrown by the local-cli action when resolvePaperclipSkillsDir() could not find the Paperclip skills directory. The CLI looks relative to its own module location and the repo checkout (process.cwd()/skills) for the bundled Paperclip skills to install into ~/.codex/skills and ~/.claude/skills. If neither candidate exists, it refuses to proceed because the subsequent install would silently skip skills.

Source

Thrown at cli/src/commands/client/agent.ts:798

          const agentRow = await ctx.api.get<Agent>(
            `${apiPath`/api/agents/${agentRef}`}?${query.toString()}`,
          );
          if (!agentRow) {
            throw new Error(`Agent not found: ${agentRef}`);
          }

          const now = new Date().toISOString().replaceAll(":", "-");
          const keyName = opts.keyName?.trim() ? opts.keyName.trim() : `local-cli-${now}`;
          const key = await ctx.api.post<CreatedAgentKey>(apiPath`/api/agents/${agentRow.id}/keys`, { name: keyName });
          if (!key) {
            throw new Error("Failed to create API key");
          }

          const installSummaries: SkillsInstallSummary[] = [];
          if (opts.installSkills !== false) {
            const skillsDir = await resolvePaperclipSkillsDir(__moduleDir, [path.resolve(process.cwd(), "skills")]);
            if (!skillsDir) {
              throw new Error(
                "Could not locate local Paperclip skills directory. Expected ./skills in the repo checkout.",
              );
            }

            installSummaries.push(
              await installSkillsForTarget(skillsDir, codexSkillsHome(), "codex"),
              await installSkillsForTarget(skillsDir, claudeSkillsHome(), "claude"),
            );
          }

          const exportsText = buildAgentEnvExports({
            apiBase: ctx.api.apiBase,
            companyId: agentRow.companyId,
            agentId: agentRow.id,
            apiKey: key.token,
          });

          if (ctx.json) {

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Run the command from the root of a full Paperclip repo checkout that includes skills/.
2. Skip skills install if you do not need them: `paperclipai agent local-cli <ref> --no-install-skills`.
3. If you need skills but are not in the repo, clone/copy the skills/ directory next to the CLI and re-run.
4. Verify __moduleDir resolution is not broken by a wrapper (pnpm dlx, npx) that changes import.meta.url semantics.

Example fix

// before — running from home dir with global CLI
paperclipai agent local-cli agt_1
// after — skip skills, or run from the repo
cd /path/to/paperclip && paperclipai agent local-cli agt_1
# or
paperclipai agent local-cli agt_1 --no-install-skills

import fs from 'node:fs';
import path from 'node:path';
function resolveSkillsDirOrDisable(installSkills: boolean, moduleDir: string, cwd: string) {
  if (installSkills === false) return null; // opt-out
  const candidates = [path.join(moduleDir, 'skills'), path.resolve(cwd, 'skills')];
  const found = candidates.find((p) => fs.existsSync(p));
  if (!found) {
    console.warn('skills/ not found; proceeding with --no-install-skills semantics');
    return null;
  }
  return found;
}

try { await runLocalCli(agentRef, { installSkills: true }); }
catch (err) {
  const msg = err instanceof Error ? err.message : '';
  if (msg.startsWith('Could not locate local Paperclip skills directory')) {
    console.error('Run from the repo root, or retry with --no-install-skills');
    process.exit(2);
  }
  throw err;
}

When it happens

Trigger: Running the globally-installed `paperclipai` binary outside the Paperclip repo, in a context where neither __moduleDir/skills nor process.cwd()/skills exists. Running from a shallow clone or a tarball install that did not ship the skills/ directory. Setting --no-install-skills is the opt-out, but here installSkills is true and the dir is missing.

Common situations: User installed the CLI via npm -g and ran `agent local-cli` from their home dir. CI checkout that excluded skills/ via sparse-checkout. Monorepo where the CLI is symlinked out of its built location.

Related errors

• Export output path ${root} exists and is not a directory.
• Export output directory ${root} already contains files. Re-r
• Output path already exists and is not a directory: ${outputD
• Output directory already exists and is not empty: ${outputDi
• Use either a skill reference or --all, not both.

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