The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
docs(agents): add create-paperclip-bundled-skill agent skill (#10477)
Dottac62fa8d6a033
diff --git a/.agents/skills/create-paperclip-bundled-skill/SKILL.md b/.agents/skills/create-paperclip-bundled-skill/SKILL.mdnew file mode 100644index 0000000000..50b4dd57ab--- /dev/null+++ b/.agents/skills/create-paperclip-bundled-skill/SKILL.md@@ -0,0 +1,265 @@+---+name: create-paperclip-bundled-skill+description: >+ Turn an idea, tweet, or task into a skill in the Paperclip skills catalog+ (packages/skills-catalog). Use when asked to FIND or MAKE a skill and publish+ it as a bundled/optional catalog skill: research prior art, reference or+ author it, add examples, regenerate the manifest, open a PR.+---++# 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++- The skill is company-private (belongs in that company's library via the+ Skills UI/API, not the shipped catalog).+- You only need a repo-internal agent skill for working on Paperclip itself —+ that goes in `.agents/skills/` or `skills/`, with no catalog machinery.++## 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:++```sh+command -v xc && xc whoami # on PATH and authenticated? if not, use the fallback below+```++```sh+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), delegate the+fetch to a teammate with X/Twitter access (e.g. the Content Strategist agent)+via a child issue: give them the URL and ask for full text of the post + thread++ any linked content.++**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.++1. **Already in the catalog?** Avoid duplicates (duplicate slugs fail the+ build):+ ```sh+ grep -i '<topic>' packages/skills-catalog/generated/catalog.json+ ls packages/skills-catalog/catalog/{bundled,optional}/*/+ ```+2. **Already in this repo?** Check `.agents/skills/`, `skills/`, and issue+ history (`gh search issues` / Paperclip board) for prior work on the topic.+3. **Published on GitHub?** Skills are conventionally a directory with a+ `SKILL.md`:+ ```sh+ 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 `<topic> 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:++- **Good external skill exists** → add it as an **external reference**+ (Step 2A). It stays attributed to and pinned at the upstream repo.+- **Partial match** → author a local skill (Step 2B) that adapts the idea;+ credit the source with a link in the SKILL.md body.+- **Nothing usable** → author a new local skill (Step 2B).++## Step 2 — Choose kind, category, and slug++- **kind**: default to `optional`. Use `bundled` only when the skill should+ ship to every Paperclip company by default — that needs explicit human/board+ direction, not your judgment call.+- **category**: reuse an existing directory when one fits (`browser`,+ `content`, `docs`, `finance`, `paperclip-operations`, `product`, `quality`,+ `research`, `software-development`). New categories are allowed but must be+ lowercase kebab-case slugs.+- **slug**: lowercase kebab-case (`^[a-z0-9]+(-[a-z0-9]+)*$`), unique across+ the whole catalog (both kinds).++The skill lives at+`packages/skills-catalog/catalog/<kind>/<category>/<slug>/` and its canonical+key is `paperclipai/<kind>/<category>/<slug>`.++## 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.++```sh+# Pin the exact commit for the chosen ref (tag or branch)+gh api repos/<owner>/<repo>/commits/<ref> --jq .sha+```++```json+{+ "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:++- `files` entries are exact relative paths or `dir/**` globs; `SKILL.md` must+ be included and must have frontmatter with `name` and `description`.+- If the upstream frontmatter declares `key`/`slug`, they must match the+ catalog placement — otherwise pick a matching slug or use the local path.+- `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+ local SKILL.md to carry them).++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):++```markdown+---+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+---+```++Optional frontmatter: `defaultInstall: true` (only for skills every new+company should get), `requires: [node, python3, ...]` for runtime deps.++Body: follow `docs/guides/agent-developer/writing-a-skill.md` — "When to use"+/ "When not to use" sections, concrete commands over prose, supporting detail+in `references/`. If the skill came from a tweet or external source, link it+in the body for attribution.++Trust level is derived from files, not declared: any `scripts/` file makes the+skill `scripts_executables` (install becomes audit-gated and you must extend+the `scriptBearing` expectation in `src/shipped-catalog.test.ts`); `assets/`+or non-markdown files make it `assets`; markdown-only skills stay+`markdown_only`. Prefer markdown-only.++## Step 3 — Write 1–2 worked examples++Create `examples/` inside the skill directory with one or two markdown files,+each a complete input → application → output walkthrough (realistic input, the+skill's steps applied, the finished artifact). These ship with the skill so+installers can judge it before running it, and they keep the trust level at+`markdown_only` because they are `.md` files.++Name them by scenario, e.g. `examples/rewrite-release-note.md`.++## Step 4 — Regenerate the manifest and update tests++Never hand-edit `generated/catalog.json`; it is deterministic build output.++```sh+pnpm --filter @paperclipai/skills-catalog build:manifest # regenerates generated/catalog.json+pnpm --filter @paperclipai/skills-catalog validate # must report no errors+```++(External references need network access to GitHub during these steps.)++Then update `packages/skills-catalog/src/shipped-catalog.test.ts`:++- add the new key to `EXPECTED_BUNDLED_KEYS` or `EXPECTED_OPTIONAL_KEYS`+ (alphabetical order);+- if the skill bears scripts, add it to the `scriptBearing` expectation.++```sh+pnpm --filter @paperclipai/skills-catalog test+```++The test suite also enforces the ≤300-char frontmatter description budget+across the repo and the ≥40-char description / non-empty roles+tags rules for+every catalog skill.++## Step 5 — Open the PR++Follow the `prepare-paperclip-pr` skill (`.agents/skills/prepare-paperclip-pr/`)+against `paperclipai/paperclip` master. The diff should contain exactly:++1. the new skill directory (SKILL.md + examples/ + supporting files, **or**+ catalog-ref.json),+2. the regenerated `generated/catalog.json`,+3. the `shipped-catalog.test.ts` expectation update.++In the PR body: link the source material (tweet URL, upstream repo), state+whether this is a new skill / adaptation / external reference, and note the+trust level. Reference PR #10410 (simplified-english) as the shape of a+minimal optional-skill PR.++## Gotchas++- `generated/catalog.json` staleness is a validation error — always rerun+ `build:manifest` after any file change inside the skill directory (the+ inventory carries per-file sha256 hashes).+- Duplicate `slug` across bundled *and* optional fails the build, not just+ duplicate keys.+- Symlinks inside a skill directory must resolve within it; directory+ symlinks are rejected — copy files in.+- The `bundled` kind and `defaultInstall` are independent axes; don't set+ `defaultInstall: true` casually on optional skills.+- For external references the builder fetches from GitHub on every manifest+ build; a moved/deleted upstream breaks the build, which is why `commit` is+ pinned — prefer upstream tags for `ref`.diff --git a/.agents/skills/create-paperclip-bundled-skill/examples/external-reference.md b/.agents/skills/create-paperclip-bundled-skill/examples/external-reference.mdnew file mode 100644index 0000000000..6c2084794d--- /dev/null+++ b/.agents/skills/create-paperclip-bundled-skill/examples/external-reference.md@@ -0,0 +1,84 @@+# Example — FIND path: tweet → existing skill → external reference++Real artifact: `packages/skills-catalog/catalog/optional/research/last30days/`.++## Input++Dotta sends a tweet praising a "last 30 days" research workflow that sweeps+Reddit/X/YouTube for what changed recently on a topic.++## Step 0 — Capture++```sh+xc get https://x.com/<author>/status/<id> --json # post text + conversation_id+xc search 'conversation_id:<id>' --archive --json # the rest of the thread+```++The thread links a GitHub repo: `mvanhorn/last30days-skill`, which already+contains a proper skill (`skills/last30days/SKILL.md` plus scripts and+references).++## Step 1 — FIND++- Not in the catalog, not in this repo.+- The upstream repo IS the skill — maintained, tagged releases, real SKILL.md.+- Verdict: **FIND** — add it as an external reference, keep attribution and+ updates upstream.++## Step 2A — catalog-ref.json++Placement: `optional` / `research` / `last30days`. Pin the release tag to an+exact commit:++```sh+gh api repos/mvanhorn/last30days-skill/commits/v3.3.0 --jq .sha+# → daca71f89eb71d0d56d01a43ed7627aa919dba4f+```++`catalog/optional/research/last30days/catalog-ref.json` (the only file in the+directory):++```json+{+ "source": {+ "type": "github",+ "hostname": "github.com",+ "owner": "mvanhorn",+ "repo": "last30days-skill",+ "ref": "v3.3.0",+ "commit": "daca71f89eb71d0d56d01a43ed7627aa919dba4f",+ "path": "skills/last30days"+ },+ "files": [+ "SKILL.md",+ "agents/openai.yaml",+ "references/**",+ "scripts/briefing.py",+ "scripts/compare.sh",+ "scripts/last30days.py",+ "scripts/lib/**",+ "scripts/setup-keychain.sh",+ "scripts/store.py",+ "scripts/watchlist.py"+ ],+ "defaultInstall": false,+ "recommendedForRoles": ["researcher", "marketer", "product-manager", "analyst"],+ "requires": ["node", "python3"],+ "tags": ["research", "last-30-days", "social-media", "trends", "citations", "reddit", "x", "youtube"]+}+```++Metadata (`recommendedForRoles`, `requires`, `tags`) lives in the JSON because+there is no local SKILL.md to carry it.++## Steps 4–5 — Manifest, tests, PR++- `pnpm --filter @paperclipai/skills-catalog build:manifest` fetches the+ pinned files from GitHub and inventories them (network required).+- The skill bundles `scripts/`, so trust level derives to+ `scripts_executables` → it must also be added to the `scriptBearing`+ expectation in `src/shipped-catalog.test.ts`, alongside+ `EXPECTED_OPTIONAL_KEYS`.+- PR diff: `catalog-ref.json`, regenerated `generated/catalog.json`, test+ expectations. PR body links both the tweet and the upstream repo, and calls+ out the elevated trust level so review is deliberate.diff --git a/.agents/skills/create-paperclip-bundled-skill/examples/new-local-skill.md b/.agents/skills/create-paperclip-bundled-skill/examples/new-local-skill.mdnew file mode 100644index 0000000000..7a0d1c4aa8--- /dev/null+++ b/.agents/skills/create-paperclip-bundled-skill/examples/new-local-skill.md@@ -0,0 +1,90 @@+# Example — MAKE path: idea → new optional catalog skill++Real run: PAP-15684 → PR #10410 (`feat(skills-catalog): add optional+/simplified-english skill`).++## Input++Task from Dotta: "make a skill that has agents write user-facing text in+Simplified English." No tweet this time — the source is a known public+specification (ASD-STE100 Simplified Technical English).++## Step 1 — FIND++- `grep -i 'simplified\|plain.english' packages/skills-catalog/generated/catalog.json`+ → no hits; nothing in `.agents/skills/` or `skills/` either.+- `gh search code --filename SKILL.md "simplified technical english"` → no+ usable published skill (only STE checker tools, no SKILL.md procedure).+- Verdict: **MAKE** a new local skill.++## Step 2 — Placement++- kind: `optional` (useful, but not something every company must ship with).+- category: `content` (existing category, fits writing/communication).+- slug: `simplified-english`.+- Path: `packages/skills-catalog/catalog/optional/content/simplified-english/`.++## Step 2B — Authoring++One markdown-only `SKILL.md` (trust level stays `markdown_only`):++```markdown+---+name: simplified-english+description: Write user-facing comments, plans, and documents in ASD-STE100 Simplified Technical English — short, unambiguous sentences with approved words and one meaning each — so readers understand them the first time.+key: paperclipai/optional/content/simplified-english+recommendedForRoles:+ - engineer+ - product+ - writer+ - devrel+tags:+ - writing+ - communication+ - clarity+ - style+---++# Simplified English++For user-facing comments, plans, and documents, write using only ASD-STE100+Simplified Technical English.++## Core rules++- Use short sentences (procedures ≤ 20 words, descriptions ≤ 25 words).+- Give one instruction per sentence.+- Use approved words with one meaning each; avoid synonyms and jargon.+...+```++Note the frontmatter hits every builder rule: description is 40–300 chars,+`key` matches the placement, roles and tags are non-empty.++## Steps 3–4 — Examples, manifest, tests++- Add `examples/rewrite-status-comment.md` showing a jargon-heavy status+ comment rewritten under the rules (before/after).+- `pnpm --filter @paperclipai/skills-catalog build:manifest` → regenerates+ `generated/catalog.json` with the new entry.+- Add `"paperclipai/optional/content/simplified-english"` to+ `EXPECTED_OPTIONAL_KEYS` in `src/shipped-catalog.test.ts` (alphabetical).+- `pnpm --filter @paperclipai/skills-catalog test` → green.++## Step 5 — PR++Four-part diff:++```+packages/skills-catalog/catalog/optional/content/simplified-english/SKILL.md+packages/skills-catalog/catalog/optional/content/simplified-english/examples/rewrite-status-comment.md+packages/skills-catalog/generated/catalog.json+packages/skills-catalog/src/shipped-catalog.test.ts+```++(The historical PR #10410 predates this skill and shipped as a three-part+diff without the `examples/` file; a run that follows this skill includes the+worked example from Step 3 in the same PR.)++PR body links the ASD-STE100 spec as the source and states trust level+`markdown_only`.