Skip to content

Commit 0787f00

Browse files
ambigos1ambigos1
committed
Merge origin/master into INS-4958 fix branch
2 parents 98562c1 + ee9d907 commit 0787f00

1,442 files changed

Lines changed: 280177 additions & 14458 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/skills/create-paperclip-bundled-skill/SKILL.md‎

Lines changed: 265 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,265 @@
1+
---
2+
name: create-paperclip-bundled-skill
3+
description: >
4+
Turn an idea, tweet, or task into a skill in the Paperclip skills catalog
5+
(packages/skills-catalog). Use when asked to FIND or MAKE a skill and publish
6+
it as a bundled/optional catalog skill: research prior art, reference or
7+
author it, add examples, regenerate the manifest, open a PR.
8+
---
9+
10+
# Create a Paperclip Bundled Skill
11+
12+
Take source material — a tweet, a task description, a blog post, "make a skill
13+
that does X" — and land it as a skill in the Paperclip skills catalog
14+
(`packages/skills-catalog/`), delivered as a reviewed PR. The catalog is the
15+
shelf every Paperclip company browses and installs from, so the bar is: correct
16+
metadata, useful instructions, worked examples, and a clean validation run.
17+
18+
The core rule is **FIND before MAKE**: if a good skill already exists (in the
19+
catalog, in this repo, or published on GitHub), reference or adapt it instead
20+
of writing a duplicate from scratch.
21+
22+
## When to use
23+
24+
- A human sends a tweet/link/idea and asks for it to become a Paperclip skill.
25+
- A task asks to bundle an existing repo skill into the catalog.
26+
- A task asks to add an external published skill to the catalog.
27+
28+
## When not to use
29+
30+
- The skill is company-private (belongs in that company's library via the
31+
Skills UI/API, not the shipped catalog).
32+
- You only need a repo-internal agent skill for working on Paperclip itself —
33+
that goes in `.agents/skills/` or `skills/`, with no catalog machinery.
34+
35+
## Step 0 — Capture the source material
36+
37+
Understand exactly what the skill should teach before writing anything.
38+
39+
**Tweets / X links.** Use the `xc` CLI (X API client). Paperclip engineering
40+
agent environments ship it preinstalled and pre-authenticated; it is not a
41+
tool you install or mint credentials for yourself. Check availability before
42+
relying on it:
43+
44+
```sh
45+
command -v xc && xc whoami # on PATH and authenticated? if not, use the fallback below
46+
```
47+
48+
```sh
49+
xc get <post-url-or-id> --json # the post itself (conversation_id, author)
50+
xc search 'conversation_id:<id>' --archive --json # rest of the thread (>7 days old needs --archive)
51+
xc user <username> # author context
52+
xc search '<topic keywords>' -n 30 # related discussion
53+
```
54+
55+
If `xc` is not on PATH, is unauthenticated, or the account lacks read access
56+
(the check above fails for any reason), delegate the
57+
fetch to a teammate with X/Twitter access (e.g. the Content Strategist agent)
58+
via a child issue: give them the URL and ask for full text of the post + thread
59+
+ any linked content.
60+
61+
**Other sources.** Fetch linked articles/READMEs directly. Record the source
62+
URL — it goes in the skill body or PR description as attribution.
63+
64+
Distill: what is the repeatable procedure? What inputs does it take? What does
65+
"done" look like? If the source is just an aspiration ("agents should write
66+
better commit messages"), you are authoring the procedure yourself — say so in
67+
the PR.
68+
69+
## Step 1 — FIND: search for an existing skill
70+
71+
Search in this order; stop when you have a clear winner.
72+
73+
1. **Already in the catalog?** Avoid duplicates (duplicate slugs fail the
74+
build):
75+
```sh
76+
grep -i '<topic>' packages/skills-catalog/generated/catalog.json
77+
ls packages/skills-catalog/catalog/{bundled,optional}/*/
78+
```
79+
2. **Already in this repo?** Check `.agents/skills/`, `skills/`, and issue
80+
history (`gh search issues` / Paperclip board) for prior work on the topic.
81+
3. **Published on GitHub?** Skills are conventionally a directory with a
82+
`SKILL.md`:
83+
```sh
84+
gh search code --filename SKILL.md "<topic>" --limit 20
85+
gh search repos "<topic> skill" --limit 20
86+
```
87+
Also check known collections (e.g. `anthropics/skills`) and do a web search
88+
for `<topic> agent skill SKILL.md`.
89+
90+
Judge candidates by: does the SKILL.md actually contain the procedure (not a
91+
stub)? Is it maintained? What does it bundle (scripts raise the trust level)?
92+
Is the license compatible with redistribution? Then pick a path:
93+
94+
- **Good external skill exists** → add it as an **external reference**
95+
(Step 2A). It stays attributed to and pinned at the upstream repo.
96+
- **Partial match** → author a local skill (Step 2B) that adapts the idea;
97+
credit the source with a link in the SKILL.md body.
98+
- **Nothing usable** → author a new local skill (Step 2B).
99+
100+
## Step 2 — Choose kind, category, and slug
101+
102+
- **kind**: default to `optional`. Use `bundled` only when the skill should
103+
ship to every Paperclip company by default — that needs explicit human/board
104+
direction, not your judgment call.
105+
- **category**: reuse an existing directory when one fits (`browser`,
106+
`content`, `docs`, `finance`, `paperclip-operations`, `product`, `quality`,
107+
`research`, `software-development`). New categories are allowed but must be
108+
lowercase kebab-case slugs.
109+
- **slug**: lowercase kebab-case (`^[a-z0-9]+(-[a-z0-9]+)*$`), unique across
110+
the whole catalog (both kinds).
111+
112+
The skill lives at
113+
`packages/skills-catalog/catalog/<kind>/<category>/<slug>/` and its canonical
114+
key is `paperclipai/<kind>/<category>/<slug>`.
115+
116+
## Step 2A — External reference path (`catalog-ref.json`)
117+
118+
The directory contains **only** `catalog-ref.json` (a directory with both
119+
`catalog-ref.json` and `SKILL.md` fails the build). The manifest builder
120+
fetches the pinned files from GitHub at build time and inventories them.
121+
122+
```sh
123+
# Pin the exact commit for the chosen ref (tag or branch)
124+
gh api repos/<owner>/<repo>/commits/<ref> --jq .sha
125+
```
126+
127+
```json
128+
{
129+
"source": {
130+
"type": "github",
131+
"hostname": "github.com",
132+
"owner": "<owner>",
133+
"repo": "<repo>",
134+
"ref": "<tag-or-branch>",
135+
"commit": "<40-char sha from above>",
136+
"path": "<dir inside the repo containing SKILL.md, or ''>"
137+
},
138+
"files": ["SKILL.md", "references/**", "scripts/run.py"],
139+
"defaultInstall": false,
140+
"recommendedForRoles": ["researcher"],
141+
"requires": ["python3"],
142+
"tags": ["topic", "keywords"]
143+
}
144+
```
145+
146+
Rules the builder enforces:
147+
148+
- `files` entries are exact relative paths or `dir/**` globs; `SKILL.md` must
149+
be included and must have frontmatter with `name` and `description`.
150+
- If the upstream frontmatter declares `key`/`slug`, they must match the
151+
catalog placement — otherwise pick a matching slug or use the local path.
152+
- `commit` must be a full 40-hex SHA; every listed file must be ≤ 1 MiB.
153+
- `recommendedForRoles`, `requires`, `tags` live in the JSON (there is no
154+
local SKILL.md to carry them).
155+
156+
See `catalog/optional/research/last30days/catalog-ref.json` for the live
157+
example, and `examples/external-reference.md` next to this skill.
158+
159+
## Step 2B — Author a local catalog skill
160+
161+
Layout:
162+
163+
```
164+
catalog/<kind>/<category>/<slug>/
165+
├── SKILL.md # required entrypoint
166+
├── examples/ # 1–2 worked examples (Step 3)
167+
├── references/ # optional deep-dive docs
168+
├── scripts/ # optional — raises trust level, avoid unless needed
169+
└── assets/ # optional templates/images
170+
```
171+
172+
`SKILL.md` frontmatter (all validated by the builder):
173+
174+
```markdown
175+
---
176+
name: <slug>
177+
description: >
178+
40–300 chars. Routing logic, not marketing: what it does, when to use it,
179+
when not to.
180+
key: paperclipai/<kind>/<category>/<slug>
181+
recommendedForRoles:
182+
- engineer # non-empty; used for staffing suggestions
183+
tags:
184+
- topic # non-empty; used for browse/search
185+
---
186+
```
187+
188+
Optional frontmatter: `defaultInstall: true` (only for skills every new
189+
company should get), `requires: [node, python3, ...]` for runtime deps.
190+
191+
Body: follow `docs/guides/agent-developer/writing-a-skill.md` — "When to use"
192+
/ "When not to use" sections, concrete commands over prose, supporting detail
193+
in `references/`. If the skill came from a tweet or external source, link it
194+
in the body for attribution.
195+
196+
Trust level is derived from files, not declared: any `scripts/` file makes the
197+
skill `scripts_executables` (install becomes audit-gated and you must extend
198+
the `scriptBearing` expectation in `src/shipped-catalog.test.ts`); `assets/`
199+
or non-markdown files make it `assets`; markdown-only skills stay
200+
`markdown_only`. Prefer markdown-only.
201+
202+
## Step 3 — Write 1–2 worked examples
203+
204+
Create `examples/` inside the skill directory with one or two markdown files,
205+
each a complete input → application → output walkthrough (realistic input, the
206+
skill's steps applied, the finished artifact). These ship with the skill so
207+
installers can judge it before running it, and they keep the trust level at
208+
`markdown_only` because they are `.md` files.
209+
210+
Name them by scenario, e.g. `examples/rewrite-release-note.md`.
211+
212+
## Step 4 — Regenerate the manifest and update tests
213+
214+
Never hand-edit `generated/catalog.json`; it is deterministic build output.
215+
216+
```sh
217+
pnpm --filter @paperclipai/skills-catalog build:manifest # regenerates generated/catalog.json
218+
pnpm --filter @paperclipai/skills-catalog validate # must report no errors
219+
```
220+
221+
(External references need network access to GitHub during these steps.)
222+
223+
Then update `packages/skills-catalog/src/shipped-catalog.test.ts`:
224+
225+
- add the new key to `EXPECTED_BUNDLED_KEYS` or `EXPECTED_OPTIONAL_KEYS`
226+
(alphabetical order);
227+
- if the skill bears scripts, add it to the `scriptBearing` expectation.
228+
229+
```sh
230+
pnpm --filter @paperclipai/skills-catalog test
231+
```
232+
233+
The test suite also enforces the ≤300-char frontmatter description budget
234+
across the repo and the ≥40-char description / non-empty roles+tags rules for
235+
every catalog skill.
236+
237+
## Step 5 — Open the PR
238+
239+
Follow the `prepare-paperclip-pr` skill (`.agents/skills/prepare-paperclip-pr/`)
240+
against `paperclipai/paperclip` master. The diff should contain exactly:
241+
242+
1. the new skill directory (SKILL.md + examples/ + supporting files, **or**
243+
catalog-ref.json),
244+
2. the regenerated `generated/catalog.json`,
245+
3. the `shipped-catalog.test.ts` expectation update.
246+
247+
In the PR body: link the source material (tweet URL, upstream repo), state
248+
whether this is a new skill / adaptation / external reference, and note the
249+
trust level. Reference PR #10410 (simplified-english) as the shape of a
250+
minimal optional-skill PR.
251+
252+
## Gotchas
253+
254+
- `generated/catalog.json` staleness is a validation error — always rerun
255+
`build:manifest` after any file change inside the skill directory (the
256+
inventory carries per-file sha256 hashes).
257+
- Duplicate `slug` across bundled *and* optional fails the build, not just
258+
duplicate keys.
259+
- Symlinks inside a skill directory must resolve within it; directory
260+
symlinks are rejected — copy files in.
261+
- The `bundled` kind and `defaultInstall` are independent axes; don't set
262+
`defaultInstall: true` casually on optional skills.
263+
- For external references the builder fetches from GitHub on every manifest
264+
build; a moved/deleted upstream breaks the build, which is why `commit` is
265+
pinned — prefer upstream tags for `ref`.

‎.agents/skills/create-paperclip-bundled-skill/examples/external-reference.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Example — FIND path: tweet → existing skill → external reference
2+
3+
Real artifact: `packages/skills-catalog/catalog/optional/research/last30days/`.
4+
5+
## Input
6+
7+
Dotta sends a tweet praising a "last 30 days" research workflow that sweeps
8+
Reddit/X/YouTube for what changed recently on a topic.
9+
10+
## Step 0 — Capture
11+
12+
```sh
13+
xc get https://x.com/<author>/status/<id> --json # post text + conversation_id
14+
xc search 'conversation_id:<id>' --archive --json # the rest of the thread
15+
```
16+
17+
The thread links a GitHub repo: `mvanhorn/last30days-skill`, which already
18+
contains a proper skill (`skills/last30days/SKILL.md` plus scripts and
19+
references).
20+
21+
## Step 1 — FIND
22+
23+
- Not in the catalog, not in this repo.
24+
- The upstream repo IS the skill — maintained, tagged releases, real SKILL.md.
25+
- Verdict: **FIND** — add it as an external reference, keep attribution and
26+
updates upstream.
27+
28+
## Step 2A — catalog-ref.json
29+
30+
Placement: `optional` / `research` / `last30days`. Pin the release tag to an
31+
exact commit:
32+
33+
```sh
34+
gh api repos/mvanhorn/last30days-skill/commits/v3.3.0 --jq .sha
35+
# → daca71f89eb71d0d56d01a43ed7627aa919dba4f
36+
```
37+
38+
`catalog/optional/research/last30days/catalog-ref.json` (the only file in the
39+
directory):
40+
41+
```json
42+
{
43+
"source": {
44+
"type": "github",
45+
"hostname": "github.com",
46+
"owner": "mvanhorn",
47+
"repo": "last30days-skill",
48+
"ref": "v3.3.0",
49+
"commit": "daca71f89eb71d0d56d01a43ed7627aa919dba4f",
50+
"path": "skills/last30days"
51+
},
52+
"files": [
53+
"SKILL.md",
54+
"agents/openai.yaml",
55+
"references/**",
56+
"scripts/briefing.py",
57+
"scripts/compare.sh",
58+
"scripts/last30days.py",
59+
"scripts/lib/**",
60+
"scripts/setup-keychain.sh",
61+
"scripts/store.py",
62+
"scripts/watchlist.py"
63+
],
64+
"defaultInstall": false,
65+
"recommendedForRoles": ["researcher", "marketer", "product-manager", "analyst"],
66+
"requires": ["node", "python3"],
67+
"tags": ["research", "last-30-days", "social-media", "trends", "citations", "reddit", "x", "youtube"]
68+
}
69+
```
70+
71+
Metadata (`recommendedForRoles`, `requires`, `tags`) lives in the JSON because
72+
there is no local SKILL.md to carry it.
73+
74+
## Steps 4–5 — Manifest, tests, PR
75+
76+
- `pnpm --filter @paperclipai/skills-catalog build:manifest` fetches the
77+
pinned files from GitHub and inventories them (network required).
78+
- The skill bundles `scripts/`, so trust level derives to
79+
`scripts_executables` → it must also be added to the `scriptBearing`
80+
expectation in `src/shipped-catalog.test.ts`, alongside
81+
`EXPECTED_OPTIONAL_KEYS`.
82+
- PR diff: `catalog-ref.json`, regenerated `generated/catalog.json`, test
83+
expectations. PR body links both the tweet and the upstream repo, and calls
84+
out the elevated trust level so review is deliberate.

0 commit comments

Comments
 (0)