How to use the Paperclip Page Publisher agent skill

What is an agent skill, and what does paperclip-page do?

An agent skill is a folder of instructions and helper scripts that an AI agent can load when a task matches the skill's description. The paperclip-page skill is designed for persistent pages such as reports, viewers, prototypes or static sites that should stay online and be shared as a link.

When triggered, the agent inspects a source directory, runs a publish helper, and reports back the printed public URL and S3 prefix. The helper is scripts/publish.sh, and the skill's documentation says it publishes to the configured Paperclip pages host, for example a URL under pages.paperclip.ing with your chosen slug as the path.

• Source directory must contain index.html at its root.
• Uploads go only to the configured bucket and prefix.
• Updates overwrite files additively and never delete remote objects.
• Local symlinks and hidden files are rejected.

Install the paperclip-page skill

Download the skill ZIP from this page and unzip it into one of two locations. For a personal setup, use ~/.claude/skills/. For a single project, use the project's .claude/skills/ folder. The unzipped folder should be named paperclip-page and contain SKILL.md, README.md and scripts/.

If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.

• Personal: ~/.claude/skills/
• Project: .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills

Set up the required environment before publishing

Live publishing needs more than the skill files. The skill requires the bash shell, AWS CLI v2, curl and jq on your PATH, plus several environment variables. The README notes that operators set up the AWS side, including CloudFront, ACM and Origin Access Control in front of a private S3 origin, so this is normally done by whoever runs your Paperclip pages bucket.

The required variables are PAPERCLIP_PAGE_BUCKET, PAPERCLIP_PAGE_BASE_URL and AWS_REGION. The uploader credentials are PAPERCLIP_PAGE_AWS_ACCESS_KEY_ID and PAPERCLIP_PAGE_AWS_SECRET_ACCESS_KEY, which come from Paperclip Secrets. You can instead use PAPERCLIP_PAGE_AWS_PROFILE. Do not set the global AWS_ACCESS_KEY_ID or AWS_SECRET_ACCESS_KEY for this, because they would affect every process in the agent run.

• bash, AWS CLI v2, curl, jq
• PAPERCLIP_PAGE_BUCKET, PAPERCLIP_PAGE_BASE_URL, AWS_REGION
• Page-uploader credentials from Paperclip Secrets, or an AWS profile
• Optional: PAPERCLIP_PAGE_DEFAULT_PREFIX, PAPERCLIP_PAGE_AWS_SESSION_TOKEN (only with the namespaced key pair)

Ask the agent to publish a page

You do not need to type the script yourself. Ask in plain language using words like deploy, host, share, or publish, and mention a static page, report, prototype or viewer. The skill is written to trigger on requests to host a persistent page outside here.now-style sharing.

The agent will normally follow a fixed workflow: check the folder contains only public static content, run a dry run to validate structure and see the resolved URL, choose a slug, then publish. If you give a stable URL path, the agent uses it as the slug. Otherwise it derives one from the folder name.

• "Publish ./site as a page with the slug quarterly-report."
• "Host this prototype folder and send me the link."
• "Update the demo page with the new files in ./site."

Run a dry run or publish manually

To validate a folder without any AWS writes, run the helper with --dry-run. This checks local structure and prints the resolved URL and prefix. When you are ready, run the publish command without the flag.

To republish an existing page, use --update. This only works when ./site/.paperclip-page/state.json exists from an earlier publish of that same source directory. Without that state file, the helper will not overwrite another page, so create a new slug instead.

Safety notes: scripts and network access

This skill runs scripts and uses the network. The helper enforces additive, public-only publishing: it never runs aws s3 sync --delete, does not require s3:DeleteObject, forces --no-follow-symlinks, and rejects hidden files except its own state file. Slugs must use lowercase ASCII letters, digits and hyphens. The agent is also told never to print AWS secret values or change bucket policy, IAM, DNS, CloudFront or ACM settings.

The skill is not a place for sensitive material. Do not publish secrets, customer data, private company material, credentials or internal logs, because the pages are public once uploaded. Keep site-wide root objects such as 404.html under operator control.

• Publish public content only.
• Review the folder before publishing; hidden files and symlinks will be rejected anyway.
• Rotate uploader credentials according to the operator runbook described in the README.

Troubleshoot common errors

The skill documents several error messages. Slug already exists means you should pick another slug or use --update from the original source directory. Missing index.html means the folder needs a root HTML file. Found symlink means you must replace symlinks with real files. AccessDenied points to the uploader IAM policy or to missing Paperclip Secrets.

If the public URL does not load after a publish, the skill suggests checking CloudFront deployment and DNS, that the object exists, and that the distribution uses HTTPS with the private S3 REST origin.

• Slug already exists: choose a new slug or update from the original directory.
• Missing index.html: point the helper at the folder containing the root HTML file.
• AccessDenied: check that the policy allows ListBucket, GetObject and PutObject for the bucket or prefix.
• Public URL fails: check CloudFront, DNS and object existence.