Pencil 设计

使用 Pencil CLI，通过自然语言描述创建专业的视觉设计。Pencil 是一款无界面设计工具，可生成 .pen 文件（一种结构化的 JSON 设计格式），并支持将其导出为图像。

环境准备

开始设计前，请确保 Pencil CLI 已正确安装并可用。

检查安装状态

which pencil || npx pencil version

若未找到 pencil 命令，请执行安装：

npm install -g @pencil.dev/cli

若因权限问题导致全局安装失败，可改为本地安装：

npm install @pencil.dev/cli

之后请改用 npx pencil（或 ./node_modules/.bin/pencil）运行，而非直接调用 pencil。 您可通过 pencil --help 命令了解所有可用子命令。

身份认证

Pencil 用户认证

使用 CLI 需要已登录 Pencil 的认证用户。首先，运行 pencil status 命令检查当前机器上的用户配置状态。

若尚未登录，可选择以下任一方式完成认证：

• 运行 pencil signup --email you@example.com --username johndoe --name "John Doe" 创建新用户；
• 运行 pencil login --email you@example.com [--code abc123] 登录已有账户，或完成新用户首次认证；
• （可选）也可通过在当前会话中设置环境变量 PENCIL_CLI_KEY 实现认证。

Claude Code 代理认证

CLI 需要认证才能运行其 AI 代理（依赖 Claude Code）。为此，系统配置中必须存在一个已认证的 Claude Code 用户，可通过环境变量或用户订阅方式完成配置。

若上述任一方式均不可用，请向用户说明可行选项，并协助其完成配置。

保持版本同步

本技能始终与 Pencil CLI npm 包（@pencil.dev/cli）保持同步。发布的 npm 包根目录下包含 SKILL.md；该包的版本号即为本技能的版本号。

检查是否存在更新的 CLI / 技能版本

• 注册表中最新版本：npm view @pencil.dev/cli version
• 本地已安装 CLI 版本：pencil version，或 npm list -g @pencil.dev/cli（全局安装） / npm list @pencil.dev/cli（项目级安装）

升级 CLI 后，请手动刷新您已复制的技能文件（代理不会自动更新您放置在配置目录中的技能文件）：

npm install -g @pencil.dev/cli

安装后从何处获取技能文件

• 从依赖树中获取：node_modules/@pencil.dev/cli/SKILL.md（此路径对全局与本地安装均适用；请从您的项目根目录或全局 node_modules 前缀处解析）。

无需克隆仓库即可获取同一文件（镜像自 npm tarball；支持第三方 CDN）：

• https://unpkg.com/@pencil.dev/cli@latest/SKILL.md
• https://cdn.jsdelivr.net/npm/@pencil.dev/cli@latest/SKILL.md

使用 @latest 可获取最新发布版本，或指定具体版本（例如 @0.2.4）以获得可复现的快照。

若您不清楚本机上技能文件应存放于何处

代理并不总能从上下文中推断出技能目录路径。当路径不明确时：

• 向用户询问：其代理或 IDE 从何处加载技能，或希望将本技能安装至哪个路径；
• 查阅对应产品的文档，搜索关键词 “skills”、“agent skills” 或 “plugins”——不同工具及版本所采用的路径可能不同；
• 您仍可不安装而直接使用技能内容：在当前会话中打开或获取上方 SKILL.md URL（unpkg / jsDelivr），即使磁盘路径未知，相关指引依然生效。如需持久化安装，请将获取到的文件复制至用户指定或文档说明的路径。

典型技能文件存放位置（请以您所用工具的最新文档为准——目录结构可能随版本变化）：

示例（请根据您的代理调整目标路径）：

curl -fsSL "https://unpkg.com/@pencil.dev/cli@latest/SKILL.md" -o .cursor/skills/pencil-design/SKILL.md

何时检查更新

• 会话初期，在首次运行 Pencil 设计命令前（对比 npm view @pencil.dev/cli version 与本地 CLI 版本），避免依据过时文档操作；
• 再次检查：当用户声明已升级 CLI，或实际行为与本文档不符（如参数、认证流程、耗时等）时；
• 无需每次执行命令前都检查：每会话一次即可，除非发生变更或报错提示版本不匹配。

创建设计

核心命令如下：

pencil --out  --prompt "" --export  --export-scale 2

关键参数说明：

• --out, -o — 指定 .pen 文件保存路径（必填）
• --prompt, -p — 设计需求描述（必填）
• --export, -e — 导出结果图像
• --export-scale — 图像分辨率缩放倍数（推荐设为 2 以获得清晰输出）
• --export-type — 导出格式：png（默认）、jpeg、webp、pdf
• --in, -i — 基于已有 .pen 文件启动（适用于迭代修改）
• --model, -m — 指定使用的 Claude 模型（默认为 Opus）

传递 Prompt 的规范

请将用户的原始请求**原样作为 prompt 传入**，切勿自行扩展、润色，或添加用户未明确提及的设计细节。Pencil CLI 内置 AI 设计师代理，可自主决策布局结构、配色方案、字体排印、间距关系及内容组织等专业事项。若在用户原始需求之外额外添加设计约束，将干扰 CLI 代理的判断逻辑，最终导致效果下降。

例如，若用户说“为一家咖啡馆制作落地页”，则 prompt 就应严格为该句，**不可**自行补充诸如“包含首屏横幅、暖色调配色、衬线字体”等主观设定。

生成耗时预期

设计生成并非瞬时完成——CLI 会运行 AI 代理，依次完成布局规划、元素构建与视觉效果验证。预计耗时如下：

• 简单设计（单张卡片、单一组件）：1–2 分钟
• 中等设计（应用界面、落地页局部模块）：2–3 分钟
• 复杂设计（完整落地页、详细数据看板）：3–5+ 分钟

请在开始生成前主动告知用户预计耗时，避免其等待时产生困惑。执行命令时建议设置充足超时时间（至少 600000ms / 10 分钟）。

展示结果

命令执行完成后，请读取导出的图像文件并向用户展示：

# 命令将图像导出至您指定的路径
pencil --out design.pen --prompt "..." --export design.png --export-scale 2

随后使用 Read 工具读取导出的 PNG 文件——由于您是多模态模型，该图像将被直接渲染显示。

设计生成后，请务必向用户展示图像。这正是用户的核心诉求——他们需要看到可视化成果。

设计迭代

当用户希望修改已有设计时，请使用 --in 参数加载上一版 .pen 文件：

pencil --in design.pen --out design-v2.pen --prompt "增大页眉尺寸，并将强调色更改为绿色" --export design-v2.png --export-scale 2

代理将读取现有设计，并在其基础上实施修改，而非从零开始重建。

对于连续快速迭代，建议采用一致的命名规范：

• design.pen → design-v2.pen → design-v3.pen
• 或复用同一文件：--in design.pen --out design.pen（覆盖写入）

工作目录

请将设计文件保存在用户当前工作目录，或其子目录（如 designs/）中。请勿使用临时目录——用户后续需要查找并持续迭代这些文件。