# Skill 接入

`@pagedrop/skill` 是一份单页的 `SKILL.md` 模板，丢进支持 Skill 的 AI 客户端即可使用。
它教 Claude Code、Codex、Cursor、Claude Desktop 等 Agent 在用户说"分享给我"、
"用 PageDrop 弄个分享链接"时，自动把当前 HTML / Markdown / TXT 文件或模型生成内容上传到 PageDrop。
MCP 服务（见 [MCP 指南](/developers/mcp)）负责提供工具；Skill 负责定义触发词、默认分享策略和脚本兜底。

## 下载

- **SKILL.md** 原始模板：<https://github.com/daogu-ai/pagedrop/blob/main/packages/skill/SKILL.md>
  （或仓库里的 `packages/skill/SKILL.md`）
- **页面内预览**完整模板：[/api/skill/raw](/api/skill/raw)
- **REST 脚本兜底**：`packages/skill/scripts/pagedrop-share.sh`

## Skill 教给助手什么

触发关键词（任意语言）：`publish`、`share`、`分享`、`发布`、
`send a link`、`render this markdown`、`pagedrop`、`用 PageDrop 弄个分享链接`。

安装后助手会自动采纳以下行为：

1. **能一次搞定就别拆** —— 优先用 `pagedrop_upload({..., share: {...}})`，
   而不是先上传再创建分享，省一次往返。
2. **默认需要登录** —— 普通"分享给我"使用 `share: { requireLogin: true }`。
3. **公开链接默认 3 次** —— 用户明确说"不需要登录 / 公开 / anyone can open"时，
   使用 `share: { requireLogin: false, maxVisits: 3 }`；用户指定次数就用指定次数。
4. **一次性就是公开一次** —— 用户说"一次性"时使用
   `share: { requireLogin: false, oneTime: true }`。
5. **密码链接默认不限次** —— 用户说"带密码"时使用
   `share: { requireLogin: false, password: "..." }`；如果同时说"几次"，再加 `maxVisits`。
6. **TXT 用纯文本模式** —— 日志、纯文本笔记、`.txt` / `.text` 文件使用 `kind: "TEXT"`；
   公开渲染时会被转义后放进 `<pre>`，不会当 HTML 执行。
7. **先校验再上传 Agent 生成的内容** —— 先调 `pagedrop_validate`；如果发现的
   issue 只是 info 级别（BOM / CRLF / Tab 等），就用 `normalized` 字段作为上传内容。
8. **错误处理** —— 基于工具错误的 `code` 字段分支：
   `RATE_LIMITED` → 等 `Retry-After` 后重试；
   `SLUG_TAKEN` → 换个变体；
   `INFECTED` → 让用户重新导出再试；
   `UNAUTHENTICATED` → 告诉用户 token 缺失或已撤销。
9. **token 来源会沉淀** —— 脚本从参数、环境变量或用户目录配置读 token；
   成功后只记 `env:PAGEDROP_API_KEY` 或 `file:...` 这种来源，不保存 token 明文。
10. **不要去 fetch 分享 URL 来验证** —— 那会被计成一次访问，
   立刻打爆 `maxVisits: 1`。

## 安装

### Claude Code

把 SKILL.md 放到 skills 目录：

```bash
mkdir -p ~/.claude/skills/pagedrop
curl -L https://raw.githubusercontent.com/daogu-ai/pagedrop/main/packages/skill/SKILL.md \
  -o ~/.claude/skills/pagedrop/SKILL.md
```

然后按 [MCP 指南](/developers/mcp) 配上 MCP 服务，Skill 引用的工具才能跑起来。

### 通用的支持 Skill 的客户端

把 `SKILL.md` 放进客户端的 skills 目录；再把 `SKILL.md` 里的 `mcp_servers`
配置思路接到客户端里。Skill 正文本身给模型读，MCP 负责真正上传。

### 没有 MCP 时的脚本兜底

如果客户端没有 MCP，但能运行 shell 脚本，也可以配置环境变量后走 REST 脚本：

```bash
export PAGEDROP_API_URL="http://117.72.193.223:10180"
export PAGEDROP_API_KEY="pd_xxxxxxxx_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
packages/skill/scripts/pagedrop-share.sh ./report.md
```

当前 PageDrop 还没有域名，脚本默认服务端就是
`http://117.72.193.223:10180`；只有接入别的部署时才需要改
`PAGEDROP_API_URL`。

也可以把 token 放在用户目录文件里，例如 `~/.pagedrop/token`、
`~/.pagedrop/config`、`~/.config/pagedrop/token`，或 macOS / Windows 对应的
PageDrop 配置目录。用户在对话里直接给 token 时，Agent 应当临时用
`PAGEDROP_API_KEY=...` 传给脚本；脚本只记住环境变量名。

脚本支持 stdin：

```bash
printf '%s' "$CONTENT" | packages/skill/scripts/pagedrop-share.sh \
  --stdin --name answer.md --kind MARKDOWN
```

默认输出目录会自动创建：`PAGEDROP_OUTPUT_DIR`、`--output-dir`，或者
state 目录下的 `out`。stdin 内容和 `last-share.json` 都会写到这里。

## 示例提示词

- "把刚才这段内容分享给我。" → 默认需要登录。
- "公开分享，不需要登录。" → 无需登录，默认 3 次访问。
- "公开分享，可以访问 10 次。" → 无需登录，10 次访问。
- "做成一次性链接。" → 无需登录，1 次访问。
- "用密码 `s3cret12` 分享给我。" → 密码链接，默认不限次数。
- "密码 `s3cret12`，最多 3 次。" → 密码 + 3 次访问。

按 Skill 的行为表，每条对应 1-2 次 MCP 工具调用，或一次脚本调用。

## 仓库里的示例

- `packages/skill/examples/meeting-notes-to-share.md` —— "笔记 → Markdown → 登录受控分享"
  这条流程的提示词 + 期望的 MCP 调用序列。
- `packages/skill/examples/web-clip-to-share.sh` —— 纯 curl 演示（不依赖 MCP）；
  接收一个 URL 或本地 HTML，打印分享 URL。
- `packages/skill/scripts/pagedrop-share.sh` —— Agent 可直接调用的一键上传脚本；
  支持 stdin、登录/公开/一次性/密码/次数/过期/slug。