Yourwebs

Name: Yourwebs
Author: sugarforever

sugarforever/yourwebs-skill

2 installs
Updated June 2, 2026
sugarforever/yourwebs-skill

Publish a self-contained HTML page to yourweb (yourwebs.cc) for a public URL, and list, fetch, update, or delete hosted pages via its REST API.

About

Publishes a single self-contained HTML file to yourweb and returns a public URL, then manages hosted pages (list, get, update, delete) via the REST API with bearer-token auth. A developer uses it to quickly host or share an HTML artifact.

POST /pages returns a served URL at <subdomain>.yourwebs.app
Token from YOURWEBS_API_TOKEN env var; rate-limited 30 publishes/hour

Yourwebs by the numbers

2 all-time installs (skills.sh)
Ranked #1,839 of 2,715 Automation & Workflows skills by installs in the Skillselion catalog
Data as of Jul 27, 2026 (Skillselion catalog sync)

npx skills add https://github.com/sugarforever/yourwebs-skill --skill yourwebs

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/sugarforever/yourwebs-skill/yourwebs.svg)](https://skillselion.com/skills/sugarforever/yourwebs-skill/yourwebs)

Installs	2
Last updated	June 2, 2026
Repository	sugarforever/yourwebs-skill ↗

What it does

Publish a self-contained HTML page to yourweb (yourwebs.cc) for a public URL, and list, fetch, update, or delete hosted pages via its REST API.

Files

SKILL.mdMarkdownGitHub ↗

Publish HTML to yourweb

Host a single self-contained HTML file on yourweb and get a public, full-screen URL. The REST API lets an agent publish a page, then list, fetch, update, and delete the pages it owns.

Two domains, by design:

`yourwebs.cc` — the dashboard and the REST API (https://yourwebs.cc/api/v1).
`yourwebs.app` — where published pages are served. A page with subdomain

my-page is served at https://my-page.yourwebs.app.

Authentication

Every call except anonymous publish needs a bearer token (ywb_...), generated by the user in the yourweb dashboard.

Read the token from the `YOURWEBS_API_TOKEN` environment variable. Never hardcode it, never write it into a file, never echo it back.

If YOURWEBS_API_TOKEN is unset, stop and ask the user to set it:

export YOURWEBS_API_TOKEN="ywb_..."   # get it from the yourweb dashboard

Only if the user explicitly prefers to paste the token inline, use it for this session — and warn them it will appear in the chat transcript, so the env var is preferred. If a project keeps it in a .env file, make sure .env is gitignored.

Publish a page (the main task)

1. Write a single, self-contained HTML file (inline CSS/JS, no external build). It must be UTF-8, contain <!doctype html> or <html>, and be ≤ 1 MB. 2. Wrap it in a JSON body and POST it. Use jq to build the JSON so the HTML is escaped correctly — never hand-concatenate HTML into a JSON string. 3. Return the url from the response to the user.

# index.html holds your self-contained page
jq -n --rawfile html index.html \
  '{html: $html, title: "My Page", subdomain: "my-page"}' \
| curl -sS -X POST https://yourwebs.cc/api/v1/pages \
    -H "Authorization: Bearer $YOURWEBS_API_TOKEN" \
    -H "Content-Type: application/json" \
    --data-binary @-

Response (HTTP 201) is a page object — hand url back to the user:

{ "id": "01J0...", "subdomain": "my-page", "url": "https://my-page.yourwebs.app",
  "title": "My Page", "size_bytes": 4096, "total_views": 0, "status": "active",
  "created_at": 1747900800000, "updated_at": 1747900800000 }

title and subdomain are optional. The page is served at https://<subdomain>.yourwebs.app. subdomain only takes effect with a token (anonymous publishes get a random subdomain) and must be 3–32 chars, lowercase a-z 0-9 -, no leading/trailing or doubled hyphen, not a reserved word. Omit it to get a random subdomain.

Manage existing pages

All of these require the token.

# List your pages -> { "pages": [ ... ] }
curl -sS https://yourwebs.cc/api/v1/pages \
  -H "Authorization: Bearer $YOURWEBS_API_TOKEN"

# Get one page
curl -sS https://yourwebs.cc/api/v1/pages/PAGE_ID \
  -H "Authorization: Bearer $YOURWEBS_API_TOKEN"

# Replace a page's HTML (body: { html })
jq -n --rawfile html index.html '{html: $html}' \
| curl -sS -X PUT https://yourwebs.cc/api/v1/pages/PAGE_ID \
    -H "Authorization: Bearer $YOURWEBS_API_TOKEN" \
    -H "Content-Type: application/json" --data-binary @-

# Delete a page -> { "deleted": true }
curl -sS -X DELETE https://yourwebs.cc/api/v1/pages/PAGE_ID \
  -H "Authorization: Bearer $YOURWEBS_API_TOKEN"

Quick reference

Method	Path	Body	Token	Success
POST	`/pages`	`{ html, title?, subdomain? }`	optional	201 page
GET	`/pages`	—	required	200 `{ pages: [...] }`
GET	`/pages/:id`	—	required	200 page
PUT	`/pages/:id`	`{ html }`	required	200 page
DELETE	`/pages/:id`	—	required	200 `{ deleted: true }`

Constraints & errors

HTML: UTF-8, contains <!doctype html>/<html>, ≤ 1 MB (the raw HTML byte size,

matching size_bytes, not the JSON body). Else 400 invalid_html — fix the HTML, don't retry unchanged.

400 subdomain_invalid: the subdomain breaks the format rules — fix it, don't

blindly retry. 409 subdomain_taken: it's valid but in use — pick another or omit.

Rate limits: 30 publishes/hour, 60 updates/hour. On 429 rate_limited, wait and

retry later rather than hammering — the window is hourly.

Errors are { "error": { "code": "...", "message": "..." } }. Common codes:

bad_request (400), invalid_html (400), subdomain_invalid (400), unauthorized / invalid_token (401), not_found (404), subdomain_taken (409), rate_limited (429), no_subdomain_available (503).

Anonymous pages (no token) auto-delete after 30 days and can't be claimed later;

publish with a token for anything you want to keep.

Full contract: see reference/api.md.

MIT License

Copyright (c) 2026 sugarforever

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

yourwebs-skill

An agent skill that teaches any coding agent (Claude Code, Codex, Cursor, and others) how to publish and manage HTML pages on yourweb — upload a self-contained HTML file and get a public, full-screen URL like https://my-page.yourwebs.app.

Install

npx skills add sugarforever/yourwebs-skill

The `skills` CLI copies the skill into whichever agent(s) you choose, so it works the same across Claude Code, Codex, Cursor, and the rest.

Get a token

The skill needs an API token to publish on your behalf:

1. Sign in at <https://yourwebs.cc> and open the dashboard. 2. Generate an API token (it looks like ywb_...). 3. Export it so the agent can read it — never paste it into source or commits:

   export YOURWEBS_API_TOKEN="ywb_..."

Then just ask your agent to "publish this page to yourweb" and it will do the rest.

What it can do

Publish a self-contained HTML file → returns a public URL.
List the pages you own.
Fetch, update (replace HTML), and delete a page.

See `SKILL.md` for the workflow and `reference/api.md` for the full REST API contract.

---

For yourweb operators: embed this on your site

Show users this snippet (e.g. on the dashboard) so they can wire up their agent in one step:

Let your AI agent publish here. Install the skill:

    npx skills add sugarforever/yourwebs-skill

Then create an API token in your dashboard and export it:

    export YOURWEBS_API_TOKEN="ywb_..."

Now ask your agent to "publish this HTML to yourweb".

yourweb REST API reference

Base URL: https://yourwebs.cc/api/v1

Authentication: Authorization: Bearer <token> where the token is ywb_..., generated in the yourweb dashboard. Read it from YOURWEBS_API_TOKEN; never hardcode or commit it. Only POST /pages works without a token (anonymous publish).

All error responses share this shape:

{ "error": { "code": "machine_code", "message": "human readable message" } }

Page object

Returned by POST /pages (201), GET /pages/:id (200), PUT /pages/:id (200), and as each element of the array from GET /pages.

{
  "id": "01J000000000000000000000",
  "subdomain": "my-page",
  "url": "https://my-page.yourwebs.app",
  "title": "My Page",
  "size_bytes": 4096,
  "total_views": 0,
  "status": "active",
  "created_at": 1747900800000,
  "updated_at": 1747900800000
}

created_at / updated_at are epoch milliseconds.

Endpoints

POST /pages — publish

Auth: optional. With a token the page is owned and permanent; anonymous pages get

a random subdomain, auto-delete after 30 days, and cannot be claimed afterward.

Body: { "html": string, "title"?: string, "subdomain"?: string }
html (required): the full HTML document.
title (optional): overrides the title; otherwise derived from <title>.
subdomain (optional): only honored with a token. Validation below.
Success: 201 with a page object.
Errors: 400 bad_request (body not JSON, or missing html),

400 invalid_html (empty, > 1 MB, not UTF-8, or no <!doctype html>/<html>), 400 subdomain_invalid, 409 subdomain_taken, 503 no_subdomain_available, 429 rate_limited (limit 30/hour, keyed by token, or by IP when anonymous).

GET /pages — list owned pages

Auth: required (401 unauthorized without a token).
Success: 200 with { "pages": [ <page object>, ... ] }.

GET /pages/:id — fetch one

Auth: required. Only the owner can read the page.
Success: 200 page object.
Errors: 401 unauthorized, 404 not_found (missing or not owned by caller).

PUT /pages/:id — replace HTML

Auth: required, owner only.
Body: { "html": string }. Same HTML validation as publish.
Success: 200 with the updated page object.
Errors: 401 unauthorized, 404 not_found, 400 bad_request,

400 invalid_html, 429 rate_limited (limit 60/hour, keyed by token).

DELETE /pages/:id — delete

Auth: required, owner only.
Success: 200 with { "deleted": true }.
Errors: 401 unauthorized, 404 not_found.

Subdomain rules (custom subdomain on publish)

3–32 characters.
Lowercase letters, digits, and hyphens: ^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$.
No leading or trailing hyphen; no doubled hyphen (--).
Not a reserved word (e.g. www, api, and other system names).
Only applied to token-authenticated requests; anonymous requests always get a

random subdomain regardless of what is sent.

HTML constraints

Non-empty, valid UTF-8 text.
Maximum 1,000,000 bytes (1 MB).
Must contain <!doctype html> or <html> (case-insensitive).

Error code summary

Code	HTTP	Meaning
`bad_request`	400	Body is not JSON, or `html` field missing/not a string
`invalid_html`	400	Empty, over 1 MB, not UTF-8, or not an HTML document
`subdomain_invalid`	400	Custom subdomain fails the validation rules
`unauthorized`	401	Endpoint needs a token and none was provided
`invalid_token`	401	Token provided but invalid or expired
`not_found`	404	Page does not exist or is not owned by the caller
`subdomain_taken`	409	Requested subdomain already in use
`rate_limited`	429	Too many requests (30 publishes/hr, 60 updates/hr)
`no_subdomain_available`	503	Could not allocate a random subdomain; retry