{"record":{"id":"4e44edfac662b307","repo":"paperclipai/paperclip","slug":"could-not-locate-local-paperclip-skills-directory","errorCode":null,"errorMessage":"Could not locate local Paperclip skills directory. Expected ./skills in the repo checkout.","messagePattern":"Could not locate local Paperclip skills directory\\. Expected \\./skills in the repo checkout\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"cli/src/commands/client/agent.ts","lineNumber":798,"sourceCode":"          const agentRow = await ctx.api.get<Agent>(\n            `${apiPath`/api/agents/${agentRef}`}?${query.toString()}`,\n          );\n          if (!agentRow) {\n            throw new Error(`Agent not found: ${agentRef}`);\n          }\n\n          const now = new Date().toISOString().replaceAll(\":\", \"-\");\n          const keyName = opts.keyName?.trim() ? opts.keyName.trim() : `local-cli-${now}`;\n          const key = await ctx.api.post<CreatedAgentKey>(apiPath`/api/agents/${agentRow.id}/keys`, { name: keyName });\n          if (!key) {\n            throw new Error(\"Failed to create API key\");\n          }\n\n          const installSummaries: SkillsInstallSummary[] = [];\n          if (opts.installSkills !== false) {\n            const skillsDir = await resolvePaperclipSkillsDir(__moduleDir, [path.resolve(process.cwd(), \"skills\")]);\n            if (!skillsDir) {\n              throw new Error(\n                \"Could not locate local Paperclip skills directory. Expected ./skills in the repo checkout.\",\n              );\n            }\n\n            installSummaries.push(\n              await installSkillsForTarget(skillsDir, codexSkillsHome(), \"codex\"),\n              await installSkillsForTarget(skillsDir, claudeSkillsHome(), \"claude\"),\n            );\n          }\n\n          const exportsText = buildAgentEnvExports({\n            apiBase: ctx.api.apiBase,\n            companyId: agentRow.companyId,\n            agentId: agentRow.id,\n            apiKey: key.token,\n          });\n\n          if (ctx.json) {","sourceCodeStart":780,"sourceCodeEnd":816,"githubUrl":"https://github.com/paperclipai/paperclip/blob/67001ec6eb96ae601aa27bc91d9b2415d665334a/cli/src/commands/client/agent.ts#L780-L816","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Run the command from the root of a full Paperclip repo checkout that includes skills/.","Skip skills install if you do not need them: `paperclipai agent local-cli <ref> --no-install-skills`.","If you need skills but are not in the repo, clone/copy the skills/ directory next to the CLI and re-run.","Verify __moduleDir resolution is not broken by a wrapper (pnpm dlx, npx) that changes import.meta.url semantics."],"exampleFix":"// before — running from home dir with global CLI\npaperclipai agent local-cli agt_1\n// after — skip skills, or run from the repo\ncd /path/to/paperclip && paperclipai agent local-cli agt_1\n# or\npaperclipai agent local-cli agt_1 --no-install-skills","handlingStrategy":"validation","validationCode":"import fs from 'node:fs';\nimport path from 'node:path';\nfunction resolveSkillsDirOrDisable(installSkills: boolean, moduleDir: string, cwd: string) {\n  if (installSkills === false) return null; // opt-out\n  const candidates = [path.join(moduleDir, 'skills'), path.resolve(cwd, 'skills')];\n  const found = candidates.find((p) => fs.existsSync(p));\n  if (!found) {\n    console.warn('skills/ not found; proceeding with --no-install-skills semantics');\n    return null;\n  }\n  return found;\n}","typeGuard":null,"tryCatchPattern":"try { await runLocalCli(agentRef, { installSkills: true }); }\ncatch (err) {\n  const msg = err instanceof Error ? err.message : '';\n  if (msg.startsWith('Could not locate local Paperclip skills directory')) {\n    console.error('Run from the repo root, or retry with --no-install-skills');\n    process.exit(2);\n  }\n  throw err;\n}","preventionTips":["Run the CLI from a full Paperclip repo checkout when using local-cli.","Pass --no-install-skills when you do not need skills installed.","If globally installed, also keep a repo checkout available for skills-backed commands.","Verify sparse-checkout includes skills/."],"tags":["cli","skills","filesystem","local-cli","packaging"],"backgroundTag":null,"analyzedSha":"67001ec6eb96ae601aa27bc91d9b2415d665334a","analyzedAt":"2026-08-12T12:05:45.408Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}