create-paperclip-bundled-skill skill

Create a Paperclip Bundled Skill

Take source material — a tweet, a task description, a blog post, "make a skill that does X" — and land it as a skill in the Paperclip skills catalog (packages/skills-catalog/), delivered as a reviewed PR. The catalog is the shelf every Paperclip company browses and installs from, so the bar is: correct metadata, useful instructions, worked examples, and a clean validation run.

The core rule is FIND before MAKE: if a good skill already exists (in the catalog, in this repo, or published on GitHub), reference or adapt it instead of writing a duplicate from scratch.

When to use

• A human sends a tweet/link/idea and asks for it to become a Paperclip skill.
• A task asks to bundle an existing repo skill into the catalog.
• A task asks to add an external published skill to the catalog.

When not to use

Skills UI/API, not the shipped catalog).

• The skill is company-private (belongs in that company's library via the

that goes in .agents/skills/ or skills/, with no catalog machinery.

• You only need a repo-internal agent skill for working on Paperclip itself —

Step 0 — Capture the source material

Understand exactly what the skill should teach before writing anything.

Tweets / X links. Use the xc CLI (X API client). Paperclip engineering agent environments ship it preinstalled and pre-authenticated; it is not a tool you install or mint credentials for yourself. Check availability before relying on it:

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

If xc is not on PATH, is unauthenticated, or the account lacks read access (the check above fails for any reason), use another authorized source or ask the user for the post, thread, and linked content. Report any unavailable context.

Other sources. Fetch linked articles/READMEs directly. Record the source URL — it goes in the skill body or PR description as attribution.

Distill: what is the repeatable procedure? What inputs does it take? What does "done" look like? If the source is just an aspiration ("agents should write better commit messages"), you are authoring the procedure yourself — say so in the PR.

Step 1 — FIND: search for an existing skill

Search in this order; stop when you have a clear winner.

build):

1. Already in the catalog? Avoid duplicates (duplicate slugs fail the

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

history (gh search issues / Paperclip board) for prior work on the topic.

1. Already in this repo? Check .agents/skills/, skills/, and issue

SKILL.md:

1. Published on GitHub? Skills are conventionally a directory with a

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

Also check known collections (e.g. anthropics/skills) and do a web search for agent skill SKILL.md.

Judge candidates by: does the SKILL.md actually contain the procedure (not a stub)? Is it maintained? What does it bundle (scripts raise the trust level)? Is the license compatible with redistribution? Then pick a path:

(Step 2A). It stays attributed to and pinned at the upstream repo.

• Good external skill exists → add it as an external reference

credit the source with a link in the SKILL.md body.

• Partial match → author a local skill (Step 2B) that adapts the idea;

• Nothing usable → author a new local skill (Step 2B).

Step 2 — Choose kind, category, and slug

ship to every Paperclip company by default — that needs explicit human/board direction, not your judgment call.

• kind: default to optional. Use bundled only when the skill should

content, docs, finance, paperclip-operations, product, quality, research, software-development). New categories are allowed but must be lowercase kebab-case slugs.

• category: reuse an existing directory when one fits (browser,

the whole catalog (both kinds).

• slug: lowercase kebab-case (^[a-z0-9]+(-[a-z0-9]+)*$), unique across

The skill lives at packages/skills-catalog/catalog//// and its canonical key is paperclipai///.

Step 2A — External reference path (catalog-ref.json)

The directory contains only catalog-ref.json (a directory with both catalog-ref.json and SKILL.md fails the build). The manifest builder fetches the pinned files from GitHub at build time and inventories them.

# 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"]
}

Rules the builder enforces:

be included and must have frontmatter with name and description.

• files entries are exact relative paths or dir/** globs; SKILL.md must

catalog placement — otherwise pick a matching slug or use the local path.

• If the upstream frontmatter declares key/slug, they must match the

local SKILL.md to carry them).

• commit must be a full 40-hex SHA; every listed file must be ≤ 1 MiB.
• recommendedForRoles, requires, tags live in the JSON (there is no

See catalog/optional/research/last30days/catalog-ref.json for the live example, and examples/external-reference.md next to this skill.

Step 2B — Author a local catalog skill

Layout:

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 (all validated by the builder):

---
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
---