Poper Skills CLI

从 Poper Skills 市场发现并安装 AI Agent 技能（claude-code、codex、copilot）。

English / 英文

技能（Skill） 是一个独立模块——可能是 prompts、工作流、MCP 配置——用于"插装"到你的 AI Agent 中。本 CLI 让你完成登录、浏览市场、把技能装到正确的 Agent 目录，以及更新 CLI 自身。

目录

• 安装
• 快速开始
• 命令一览
  • poper auth login
  • poper auth logout
  • poper auth status
  • poper skills search
  • poper skills list
  • poper skills info
  • poper skills install
  • poper skills uninstall
  • poper update
• Agent 与作用域
• 环境变量
• 代理（Clash / 公司网）
• 本地开发
• 发布新版本
• 常见问题
• 许可证

安装

npm i -g @poper-ai/cli

或者使用 pnpm：

pnpm add -g @poper-ai/cli

验证：

poper --version
poper --help

环境要求：Node.js ≥ 20。

快速开始

# 1. 登录（默认会自动打开浏览器）
poper auth login

# 2. 搜索技能
poper skills search creator

# 3. 查看版本和详情
poper skills info skill-creator

# 4. 安装（默认装最新版到 Claude Code 用户目录）
poper skills install skill-creator

# 5. 看看本地装了哪些技能
poper skills list --installed

命令一览

poper auth login

CLI 登录认证。默认走浏览器流程——自动打开激活页，你在浏览器确认，CLI 轮询并保存 token。

poper auth login                      # 浏览器流程（默认）
poper auth login --token <TOKEN>      # 直接传 token（CI 场景）

Token 优先存入操作系统的 keychain（依赖 keytar），不可用时降级到 ~/.poper/credentials。

poper auth logout

清除本机保存的凭证。

poper auth logout

poper auth status

打印当前登录状态以及 token 所属用户。

poper auth status

poper skills search

按关键词搜索市场，可选过滤器进一步缩小范围。

poper skills search <query> [--category <c>] [--platform <p>]

示例：

poper skills search creator
poper skills search "code review" --platform claude-code
poper skills search agent --category prompts

返回一个自适应表格：Slug | Name | Author | Ver | Category | ↓ | ★。 其中 slug 是后续 install / info / uninstall 用的唯一标识。

poper skills list

列出市场全部技能，或仅显示已在本机安装的。

poper skills list                     # 浏览市场
poper skills list --installed         # 扫描本地 agent 目录

poper skills info

查看单个技能的元信息及全部历史版本。

poper skills info <slug>

# 例
poper skills info skill-creator

poper skills install

把技能安装到对应 Agent 的 skills 目录。

poper skills install <slug>[@<version>] [选项]

选项：

| 选项 | 默认值 | 说明 | | --------------------- | ------------ | ----------------------------------------------- | | --agent <id> | claude-code| claude-code | codex | copilot | | --scope <scope> | user | user（家目录）| project（当前目录） | | -v, --ver <version> | latest | 指定具体版本 | | -f, --force | 关闭 | 已存在时不询问，直接覆盖 |

示例：

poper skills install skill-creator                       # 装最新
poper skills install [email protected]                 # npm 风格指定版本
poper skills install skill-creator -v 1.0.0              # 短参指定版本
poper skills install skill-creator --agent codex --scope project
poper skills install [email protected] --force         # 覆盖

为什么用 -v / --ver 而不是 --version？ --version 已经被 CLI 占用（用来打印 CLI 自身版本）。指定技能版本请用 --ver 或 slug@version 写法。

poper skills uninstall

卸载已安装的技能。

poper skills uninstall <slug> [--agent <id>] [--scope <scope>] [-y]

示例：

poper skills uninstall skill-creator
poper skills uninstall skill-creator -y                  # 跳过确认
poper skills uninstall skill-creator --agent codex --scope project

poper update

检查并更新 CLI 自身。

poper update                          # 检查 + 提示 + 安装
poper update -y                       # 检查 + 直接装，不询问
poper update --check                  # 仅检查，不安装

会自动识别你的安装方式：

• 全局安装（npm i -g、pnpm add -g、yarn global add）→ 调用对应包管理器升级。
• 本地软链（npm link，开发场景）→ 不会动你的安装，会提示去执行 git pull && pnpm build。

Agent 与作用域

| Agent | 用户作用域路径 | 项目作用域路径 | | --------------- | ------------------------------- | ------------------------------------ | | claude-code (默认) | ~/.claude/skills/<slug> | ./.claude/skills/<slug> | | codex | ~/.codex/skills/<slug> | ./.codex/skills/<slug> | | copilot | ~/.copilot/skills/<slug> | ./.copilot/skills/<slug> |

• --scope user（默认）：装到当前 OS 用户的家目录。
• --scope project：装到当前工作目录——可以一起 commit 进 git，让队友拿到同样的技能集。

环境变量

| 变量 | 用途 | | --------------- | -------------------------------------------------------------------------- | | POPER_API_URL | 覆盖 API 地址，默认 https://poper-skills.fangchangkemao.com | | HTTPS_PROXY | HTTPS 代理（Clash、公司内网等） | | HTTP_PROXY | HTTP 代理 |

代理（Clash / 公司网）

Node 内置的 fetch 默认不会读取 HTTPS_PROXY。本 CLI 内置了 undici，启动时如果检测到以下任一变量就会自动走代理：

• HTTPS_PROXY / https_proxy
• HTTP_PROXY / http_proxy

所以你 Clash 开在 127.0.0.1:7890 的话，shell 里设了变量就能直接用：

export HTTPS_PROXY=http://127.0.0.1:7890
poper auth login   # 会走代理

临时绕过代理：

unset HTTPS_PROXY https_proxy

本地开发

git clone <本仓库>
cd cli
pnpm install
pnpm build       # tsc + 自动 chmod +x dist/index.js
npm link         # 让全局 `poper` 指向你本地构建
poper --help

常用脚本：

pnpm dev         # tsc --watch
pnpm clean       # rm -rf dist
pnpm build       # 完整构建

撤销本地链接、回到 npm 上的版本：

npm unlink -g @poper-ai/cli
npm i -g @poper-ai/cli

发布新版本

cd cli
npm version patch        # 0.1.0 → 0.1.1（也可以 minor / major）
npm publish              # 自动跑 prepublishOnly: clean + build

prepublishOnly 会自动 pnpm clean && pnpm build，不用你手动 build。

如果遇到 403 ... Two-factor authentication ... required：

1. 去 npm tokens 页面。
2. 生成 Granular Access Token，勾上 Bypass 2FA for publishing，权限选 read/write，包绑定 @poper-ai/cli。
3. 写入 ~/.npmrc：

   //registry.npmjs.org/:_authToken=npm_xxxxxxxxxxxx

4. 再 npm publish。

常见问题

poper: command not found 要么是用 npm i 装到本地了，要么是全局 node_modules/.bin 不在 PATH 里：

npm i -g @poper-ai/cli
echo $PATH | tr ':' '\n' | grep -E 'node_modules.bin'

zsh: permission denied: poper（本地开发场景） 构建时 tsc 把可执行位抹掉了。新的 build 脚本会自动补 chmod +x dist/index.js，重新构建一次即可。

fetch failed 通常是开了代理但 Node fetch 读不到。设置 HTTPS_PROXY 让 CLI 自动走代理——见 代理章节。

npm link 报 EEXIST: file already exists 全局目录残留了旧的 poper（一般在 /opt/homebrew/bin/poper）。删了重试：

rm $(which poper)
npm link

许可证

MIT，详见 LICENSE。