create-paperclip-bundled-skill

创建 Paperclip 捆绑技能

将源材料——推文、任务描述、博客文章或“创建一个能完成 X 的技能”——作为技能收入 Paperclip 技能目录（packages/skills-catalog/），并以经过审核的 PR 交付。该目录是所有 Paperclip 公司浏览和安装技能的货架，因此标准是：元数据正确、说明实用、示例完整，并且验证流程顺利通过。

核心原则是 先查找，再创建：如果已有不错的技能（在目录中、本仓库中或已发布到 GitHub），就引用或改编它，而不是从头编写重复内容。

适用场景

• 有人发送推文、链接或想法，并要求将其变成 Paperclip 技能。
• 任务要求将现有仓库技能打包到目录中。
• 任务要求将外部已发布的技能添加到目录中。

不适用场景

• 技能属于某家公司私有内容（应通过 Skills UI/API 放入该公司的库，而不是放入随产品发布的目录）。
• 你只需要一个用于 Paperclip 项目内部工作的仓库内部 Agent 技能——应将其放在 .agents/skills/ 或 skills/ 中，无需目录相关流程。

步骤 0 — 收集源材料

开始编写前，先准确理解该技能应该教授什么。

推文 / X 链接。 使用 xc CLI（X API 客户端）。Paperclip 工程 Agent 环境已预装并预先完成身份验证；你无需自行安装该工具或获取凭据。依赖它之前，先检查是否可用：

command -v xc && xc whoami    # on PATH and authenticated? if not, use the fallback below

xc get <post-url-or-id> --json        # the post itself (conversation_id, author)
xc search 'conversation_id:<id>' --archive --json   # rest of the thread (>7 days old needs --archive)
xc user <username>                    # author context
xc search '<topic keywords>' -n 30    # related discussion

如果 xc 不在 PATH 中、未通过身份验证，或该账号没有读取权限（上述检查因任何原因失败），请通过子任务将抓取工作委派给有 X/Twitter 访问权限的队友（例如 Content Strategist Agent）：把 URL 发给对方，并要求提供帖子的完整文本、整个讨论串以及任何链接内容。

其他来源。 直接获取链接文章或 README。记录源 URL——应在技能正文或 PR 描述中注明出处。

提炼：可重复执行的流程是什么？它需要哪些输入？怎样才算“完成”？如果源材料只是一个愿景（例如“Agent 应该写出更好的提交消息”），那么流程需要由你自行编写——请在 PR 中说明这一点。

步骤 1 — 查找：搜索现有技能

按以下顺序搜索；找到明确合适的技能后即可停止。

1. 目录中已有吗？ 避免重复（重复的 slug 会导致构建失败）：

   grep -i '<topic>' packages/skills-catalog/generated/catalog.json
   ls packages/skills-catalog/catalog/{bundled,optional}/*/
   

2. 本仓库中已有吗？ 检查 .agents/skills/、skills/ 和 issue 历史记录（gh search issues / Paperclip 看板），查找该主题的既有工作。
3. 已发布到 GitHub 吗？ 技能通常是一个包含 SKILL.md 的目录：

   gh search code --filename SKILL.md "<topic>" --limit 20
   gh search repos "<topic> skill" --limit 20
   

   还要检查已知集合（例如 anthropics/skills），并在网上搜索 <topic> agent skill SKILL.md。

评估候选技能时，考虑：SKILL.md 是否确实包含操作流程（而不是空壳）？是否仍在维护？它捆绑了什么内容（脚本能提升可信度）？许可证是否允许再分发？然后选择一种做法：

• 存在合适的外部技能 → 将其作为外部引用添加（步骤 2A）。保留上游仓库署名，并固定到该仓库。
• 部分匹配 → 编写本地技能（步骤 2B）来改编其思路；在 SKILL.md 正文中附上链接并注明来源。
• 没有可用内容 → 编写新的本地技能（步骤 2B）。

步骤 2 — 选择类型、类别和标识名

• kind：默认使用 optional。只有在技能应默认提供给每家 Paperclip 公司时，才使用 bundled——这需要明确的人类／董事会指示，而不是由你自行判断。
• category：如果有合适的现有目录，请重复使用（browser、content、docs、finance、paperclip-operations、product、quality、research、software-development）。可以新建类别，但必须使用小写 kebab-case 标识名。
• slug：使用小写 kebab-case（^[a-z0-9]+(-[a-z0-9]+)*$），且在整个目录（两种类型）中唯一。

技能存放在 packages/skills-catalog/catalog/<kind>/<category>/<slug>/，其规范键为 paperclipai/<kind>/<category>/<slug>。

步骤 2A — 外部引用路径（catalog-ref.json）

该目录中只能包含 catalog-ref.json（同时包含 catalog-ref.json 和 SKILL.md 的目录无法通过构建）。清单构建器会在构建时从 GitHub 获取固定版本的文件并编制索引。

# Pin the exact commit for the chosen ref (tag or branch)
gh api repos/<owner>/<repo>/commits/<ref> --jq .sha

{
  "source": {
    "type": "github",
    "hostname": "github.com",
    "owner": "<owner>",
    "repo": "<repo>",
    "ref": "<tag-or-branch>",
    "commit": "<40-char sha from above>",
    "path": "<dir inside the repo containing SKILL.md, or ''>"
  },
  "files": ["SKILL.md", "references/**", "scripts/run.py"],
  "defaultInstall": false,
  "recommendedForRoles": ["researcher"],
  "requires": ["python3"],
  "tags": ["topic", "keywords"]
}

构建器会强制执行以下规则：

• files 条目必须是准确的相对路径或 dir/** glob；必须包含 SKILL.md，且其中必须有包含 name 和 description 的 frontmatter。
• 如果上游 frontmatter 声明了 key／slug，它们必须与目录中的位置相匹配——否则请选择匹配的标识名，或使用本地路径。
• commit 必须是完整的 40 位十六进制 SHA；列出的每个文件都必须 ≤ 1 MiB。
• recommendedForRoles、requires、tags 放在 JSON 中（没有本地 SKILL.md 来承载这些字段）。

请参阅 catalog/optional/research/last30days/catalog-ref.json 中的实际示例，以及此技能旁边的 examples/external-reference.md。

步骤 2B — 编写本地目录技能

目录结构：

catalog/<kind>/<category>/<slug>/
├── SKILL.md          # required entrypoint
├── examples/         # 1–2 worked examples (Step 3)
├── references/       # optional deep-dive docs
├── scripts/          # optional — raises trust level, avoid unless needed
└── assets/           # optional templates/images

SKILL.md frontmatter（均由构建器验证）：

---
name: <slug>
description: >
  40–300 chars. Routing logic, not marketing: what it does, when to use it,
  when not to.
key: paperclipai/<kind>/<category>/<slug>
recommendedForRoles:
  - engineer            # non-empty; used for staffing suggestions
tags:
  - topic               # non-empty; used for browse/search
---

可选 frontmatter：defaultInstall: true（仅适用于每家新公司都应获得的技能），用于运行时依赖项的 requires: [node, python3, ...]。

正文：遵循 docs/guides/agent-developer/writing-a-skill.md——包含“When to use”／“When not to use”章节，优先使用具体命令而非说明性文字，并将补充详情放入 references/。如果技能源自推文或外部来源，请在正文中添加链接以注明出处。

信任级别根据文件推导，而非手动声明：任何 scripts/ 文件都会使技能变为 scripts_executables（安装会受到审计门控，你必须在 src/shipped-catalog.test.ts 中扩展 scriptBearing 预期）；assets/ 或非 Markdown 文件会使技能变为 assets；仅含 Markdown 的技能则保持为 markdown_only。优先使用仅含 Markdown 的技能。

步骤 3 — 编写 1–2 个完整示例

在技能目录中创建 examples/，并放入一到两个 Markdown 文件，每个文件都应完整展示输入 → 应用 → 输出（真实的输入、应用技能步骤的过程、完成的成果）。这些文件会随技能一起发布，以便安装者在运行前进行评估；由于它们是 .md 文件，也会让技能保持 markdown_only 信任级别。

按场景为文件命名，例如 examples/rewrite-release-note.md。

步骤 4 — 重新生成清单并更新测试

切勿手动编辑 generated/catalog.json；它是确定性构建输出。

pnpm --filter @paperclipai/skills-catalog build:manifest   # regenerates generated/catalog.json
pnpm --filter @paperclipai/skills-catalog validate         # must report no errors

（在这些步骤中，外部引用需要访问 GitHub 网络。）

然后更新 packages/skills-catalog/src/shipped-catalog.test.ts：

• 将新键按字母顺序添加到 EXPECTED_BUNDLED_KEYS 或 EXPECTED_OPTIONAL_KEYS；
• 如果技能包含脚本，将其添加到 scriptBearing 预期中。

pnpm --filter @paperclipai/skills-catalog test

测试套件还会检查整个代码库中的 frontmatter 描述是否不超过 300 个字符，并验证每个目录技能的描述是否不少于 40 个字符，以及角色和标签是否非空。

第 5 步 — 发起 PR

针对 paperclipai/paperclip 的 master 分支，按照 prepare-paperclip-pr 技能（.agents/skills/prepare-paperclip-pr/）操作。差异应当恰好包含：

1. 新技能目录（SKILL.md + examples/ + 支持文件，或 catalog-ref.json），
2. 重新生成的 generated/catalog.json，
3. shipped-catalog.test.ts 中的预期值更新。

在 PR 正文中：链接源材料（推文 URL、上游仓库），说明这是新技能、改编技能还是外部引用，并注明信任级别。可参考 PR #10410（simplified-english），了解精简版可选技能 PR 的范例。

注意事项

• generated/catalog.json 过时会导致验证失败——技能目录中的任何文件发生更改后，都要重新运行 build:manifest（清单包含每个文件的 sha256 哈希值）。
• 内置技能和可选技能之间的 slug 重复会导致构建失败，不仅仅是键重复。
• 技能目录中的符号链接必须指向目录内的内容；不允许使用目录符号链接——请将文件复制进去。
• bundled 类型和 defaultInstall 是相互独立的维度；不要随意将可选技能的 defaultInstall: true。
• 对于外部引用，构建器在每次清单构建时都会从 GitHub 获取内容；上游内容移动或删除会导致构建失败，因此需要固定 commit——ref 优先使用上游标签。