Paperclip Page
Use this skill to publish a static directory to the configured Paperclip pages
host, for example https://pages.paperclip.ing/<slug>/.
Requirements
- Source directory contains
index.html at its root.
aws CLI v2, curl, and jq are available on PATH for live publishes.
- Environment variables are configured:
PAPERCLIP_PAGE_BUCKET
PAPERCLIP_PAGE_BASE_URL
AWS_REGION
PAPERCLIP_PAGE_AWS_ACCESS_KEY_ID and PAPERCLIP_PAGE_AWS_SECRET_ACCESS_KEY
with the page-uploader credentials from Paperclip Secrets
- Optional environment variables:
PAPERCLIP_PAGE_DEFAULT_PREFIX
PAPERCLIP_PAGE_AWS_PROFILE (alternative to the namespaced key pair)
PAPERCLIP_PAGE_AWS_SESSION_TOKEN (only together with the namespaced key
pair)
Do not bind the page-uploader credentials as global AWS_ACCESS_KEY_ID /
AWS_SECRET_ACCESS_KEY: static env keys take precedence over AWS_PROFILE in
every AWS SDK, so global names silently replace the host identity for every
process in the agent run. The namespaced variables scope the uploader identity
to this helper only. The ambient credential chain still works as a fallback
when none of the PAPERCLIP_PAGE_AWS_* credential variables are set.
Workflow
- Inspect the source directory and confirm it is public static content only.
- Run
scripts/publish.sh <dir> --dry-run to validate local structure and see
the resolved URL/prefix.
- Choose a slug:
- Use
--slug <slug> when the user gave a stable URL path.
- Omit
--slug to derive one from the source directory name.
- Publish:
.agents/skills/paperclip-page/scripts/publish.sh ./site --slug my-page
- Return the printed public URL and S3 prefix to the issue/user.
Update Workflow
Updates are additive overwrites only. The helper never deletes remote objects.
.agents/skills/paperclip-page/scripts/publish.sh ./site --slug my-page --update
When the target prefix already exists, --update requires local ownership proof
from ./site/.paperclip-page/state.json generated by an earlier publish from
that same source directory. Without that state, create a new slug instead of
overwriting another page.
Safety Rules
- Publish public content only. Do not publish secrets, customer data, private
company material, credentials, or internal logs.
- Never print AWS secret values.
- Never change bucket policy, IAM, DNS, CloudFront, or ACM settings from this
skill. Setup belongs to an operator runbook, not the publish helper.
- Never upload outside the configured bucket and prefix.
- Never use
aws s3 sync --delete or require s3:DeleteObject in v1.
- The helper forces
--no-follow-symlinks and fails if any source symlink is
present.
- The helper rejects hidden files and dot-segment paths except its own
.paperclip-page/state.json.
- Slugs and prefix segments must use lowercase ASCII letters, digits, and
hyphens only.
- Keep site-wide root objects such as
404.html operator-managed; publishes
always target <slug>/... or <default-prefix>/<slug>/....
Troubleshooting
Slug already exists: choose a different slug or use --update from the
original source directory containing .paperclip-page/state.json.
Missing index.html: build the static site first or point the helper at the
directory that contains the root HTML file.
Found symlink: replace symlinks with real files before publishing.
AccessDenied: confirm the uploader IAM policy allows ListBucket,
GetObject, and PutObject for the configured bucket/prefix, and that the
agent received the Paperclip Secrets.
- Public URL verification failed: check CloudFront deployment/DNS, object
existence, and that the distribution uses HTTPS with the private S3 REST
origin.
See README.md next to this skill for operator setup, AWS policy examples,
credential rotation, and install/attach commands.
1---
2name: paperclip-page
3description: >
4 Publish static HTML pages and asset folders to the Paperclip S3/CloudFront page
5 host. Use when asked to deploy, host, or share a persistent page, viewer,
6 prototype, report, or static site without here.now.
7metadata:
8 source: https://skillmd.com/skills/paperclipai/paperclip-page
9---
10
11# Paperclip Page
12
13Use this skill to publish a static directory to the configured Paperclip pages
14host, for example `https://pages.paperclip.ing/<slug>/`.
15
16## Requirements
17
18- Source directory contains `index.html` at its root.
19- `aws` CLI v2, `curl`, and `jq` are available on PATH for live publishes.
20- Environment variables are configured:
21 - `PAPERCLIP_PAGE_BUCKET`
22 - `PAPERCLIP_PAGE_BASE_URL`
23 - `AWS_REGION`
24 - `PAPERCLIP_PAGE_AWS_ACCESS_KEY_ID` and `PAPERCLIP_PAGE_AWS_SECRET_ACCESS_KEY`
25 with the page-uploader credentials from Paperclip Secrets
26- Optional environment variables:
27 - `PAPERCLIP_PAGE_DEFAULT_PREFIX`
28 - `PAPERCLIP_PAGE_AWS_PROFILE` (alternative to the namespaced key pair)
29 - `PAPERCLIP_PAGE_AWS_SESSION_TOKEN` (only together with the namespaced key
30 pair)
31
32Do not bind the page-uploader credentials as global `AWS_ACCESS_KEY_ID` /
33`AWS_SECRET_ACCESS_KEY`: static env keys take precedence over `AWS_PROFILE` in
34every AWS SDK, so global names silently replace the host identity for every
35process in the agent run. The namespaced variables scope the uploader identity
36to this helper only. The ambient credential chain still works as a fallback
37when none of the `PAPERCLIP_PAGE_AWS_*` credential variables are set.
38
39## Workflow
40
411. Inspect the source directory and confirm it is public static content only.
422. Run `scripts/publish.sh <dir> --dry-run` to validate local structure and see
43 the resolved URL/prefix.
443. Choose a slug:
45 - Use `--slug <slug>` when the user gave a stable URL path.
46 - Omit `--slug` to derive one from the source directory name.
474. Publish:
48
49```bash
50.agents/skills/paperclip-page/scripts/publish.sh ./site --slug my-page
51```
52
535. Return the printed public URL and S3 prefix to the issue/user.
54
55## Update Workflow
56
57Updates are additive overwrites only. The helper never deletes remote objects.
58
59```bash
60.agents/skills/paperclip-page/scripts/publish.sh ./site --slug my-page --update
61```
62
63When the target prefix already exists, `--update` requires local ownership proof
64from `./site/.paperclip-page/state.json` generated by an earlier publish from
65that same source directory. Without that state, create a new slug instead of
66overwriting another page.
67
68## Safety Rules
69
70- Publish public content only. Do not publish secrets, customer data, private
71 company material, credentials, or internal logs.
72- Never print AWS secret values.
73- Never change bucket policy, IAM, DNS, CloudFront, or ACM settings from this
74 skill. Setup belongs to an operator runbook, not the publish helper.
75- Never upload outside the configured bucket and prefix.
76- Never use `aws s3 sync --delete` or require `s3:DeleteObject` in v1.
77- The helper forces `--no-follow-symlinks` and fails if any source symlink is
78 present.
79- The helper rejects hidden files and dot-segment paths except its own
80 `.paperclip-page/state.json`.
81- Slugs and prefix segments must use lowercase ASCII letters, digits, and
82 hyphens only.
83- Keep site-wide root objects such as `404.html` operator-managed; publishes
84 always target `<slug>/...` or `<default-prefix>/<slug>/...`.
85
86## Troubleshooting
87
88- `Slug already exists`: choose a different slug or use `--update` from the
89 original source directory containing `.paperclip-page/state.json`.
90- `Missing index.html`: build the static site first or point the helper at the
91 directory that contains the root HTML file.
92- `Found symlink`: replace symlinks with real files before publishing.
93- `AccessDenied`: confirm the uploader IAM policy allows `ListBucket`,
94 `GetObject`, and `PutObject` for the configured bucket/prefix, and that the
95 agent received the Paperclip Secrets.
96- Public URL verification failed: check CloudFront deployment/DNS, object
97 existence, and that the distribution uses HTTPS with the private S3 REST
98 origin.
99
100See `README.md` next to this skill for operator setup, AWS policy examples,
101credential rotation, and install/attach commands.