--- version: 0.7.0 name: create-hunk description: | Create claimable static AI-generated websites on Hunk from a CLI, then push, update, and delete after the user claims them. Use when the user asks to publish, deploy, host, share, or update a generated HTML/CSS/JavaScript site. allowed-tools: - Bash(npx:*) - Bash(bunx:*) - Bash(hunk:*) license: UNLICENSED metadata: author: 851 Labs url: https://hunk.851.sh openclaw: emoji: "" homepage: https://hunk.851.sh requires: bins: - hunk install: - kind: node package: "@851-labs/hunk" bins: [hunk] user-invocable: true --- # Create Hunk Use Hunk to publish static AI-generated websites from a local directory. Hunk uploads HTML, CSS, JavaScript, and static assets, then gives the site a workspace-scoped hunk URL. ## Skill Installation Install this skill in an agent workspace: ```sh npx skills add https://hunk.851.sh npx skills add https://hunk.851.sh/skill.md ``` ## Installing Run the CLI directly: ```sh npx @851-labs/hunk@latest ``` Or install it globally: ```sh npm install -g @851-labs/hunk@latest hunk ``` If the user uses Bun, `bunx @851-labs/hunk ` also works. ## Core Flow Copy this checklist and track progress: - Step 1: Confirm the static site directory - Step 2: Create the hunk without logging in first - Step 3: Give the user the claim link - Step 4: Push later changes after claim - Step 5: Manage the claimed hunk ### Step 1: Confirm The Static Site Directory Find the directory that contains the generated site. It must contain `index.html`. Before running Hunk commands, inspect the directory: ```sh ls find . -maxdepth 2 -type f ``` Hunk uploads regular files except `.DS_Store`, `.git`, `.hunk`, and `node_modules`. Do not create or overwrite site files unless the user asked you to edit the website. ### Step 2: Create The Hunk Create a new hunk from the current directory: ```sh npx @851-labs/hunk@latest create ``` Or pass the site directory explicitly: ```sh npx @851-labs/hunk@latest create ./site ``` Hunks are workspace-visible by default. To create a public hunk: ```sh npx @851-labs/hunk@latest create ./site --public npx @851-labs/hunk@latest create ./site --visibility public ``` Set the initial display name or URL slug only when the user asks for them: ```sh npx @851-labs/hunk@latest create ./site --name "Landing Page" npx @851-labs/hunk@latest create ./site --name "Landing Page" --slug landing-page ``` Do not run `hunk login` before creating a hunk unless the user explicitly asks you to authenticate first. If the CLI is not already authenticated, `create` still uploads the site and prints a Hunk app claim URL. If the directory has an unlinked `.hunk/config.json`, `create` merges in the new hunk id and the Hunk config schema URL. If the directory already has `.hunk/config.json` with a hunk id and the user explicitly wants a separate new hunk: ```sh npx @851-labs/hunk@latest create ./site --force ``` The command writes `.hunk/config.json` so future pushes target the same hunk. ### Step 3: Give The User The Claim Link When the agent is not authenticated, `create` prints a claim URL like: ```txt https://app.hunk.851.sh/claim/... ``` Give that claim URL to the user and ask them to open it. The claim page lets the user attach the hunk to their workspace. Do not try to complete the browser claim flow for the user. If `create` prints a workspace dashboard URL instead, the CLI was already authenticated and the hunk is already claimed. ### Step 4: Push Later Changes After Claim After editing files in a linked directory, push changes: ```sh npx @851-labs/hunk@latest push ``` Or pass a linked directory: ```sh npx @851-labs/hunk@latest push ./site ``` Use `push`, not `create`, when `.hunk/config.json` already exists and the user wants to update the existing hunk. `push`, `create`, and commands that read linked directories validate `.hunk/config.json` against the local copy of the schema served at `https://hunk.851.sh/schemas/config/v1.json` in production and `http://hunk.localhost:3000/schemas/config/v1.json` in development. If validation fails, fix the reported field before retrying, or use `hunk create --force` only when the user wants to replace the local hunk link with a new hunk. If the user has not opened the claim URL yet, `push` can stop with a message that Hunk is waiting for browser login. In that case, give the claim URL to the user again and wait until they claim it before retrying `push`. For automatic browser reloads after updates, include `` in each HTML document ``. ### Step 5: Manage The Claimed Hunk Create prints a claim URL when unauthenticated, and create or push print the Hunk dashboard URL when the hunk is claimed: ```txt https://app.hunk.851.sh/your-workspace/your-site ``` Open or share the printed URL with the user. List workspace hunks: ```sh npx @851-labs/hunk@latest list ``` Pull a hunk by linked directory, slug, or id: ```sh npx @851-labs/hunk@latest pull old-site ./site ``` Update the linked hunk: ```sh npx @851-labs/hunk@latest update --name "Landing Page" npx @851-labs/hunk@latest update ./site --slug landing-page ``` Use `--name` for the display name only. Use `--slug` only when the user explicitly wants the hunk URL to change. Use `--public` or `--visibility public` only after confirming the user wants the hunk to be public. Delete the linked hunk only when the user explicitly asks for permanent deletion: ```sh npx @851-labs/hunk@latest delete --yes npx @851-labs/hunk@latest delete ./site --yes ``` Delete removes the remote hunk and deployments, then removes the local `.hunk/config.json` link. It does not remove site files or the `.hunk` directory. ## Commands ```sh hunk login [--json] hunk logout [--json] hunk whoami [--json] hunk list [--json] [--query ] hunk feedback [--json] hunk folder hunk folder tree [--json] hunk folder list [--json] hunk folder create [--parent ] [--json] hunk folder rename [--json] hunk folder delete --yes [--json] hunk move [--into |--root] [--before |--after ] [--json] hunk create [dir] [--name ] [--slug ] [--visibility public|workspace] [--public] [--force] [--json] hunk pull [target] [dir] [--force] [--json] hunk push [dir] [--watch] [--json] hunk update [target] [--name ] [--slug ] [--visibility public|workspace] [--json] hunk delete [target] --yes [--json] ``` ## Important - Always inspect the target directory before creating or pushing a hunk. - For agents, prefer unauthenticated `create` first and give the printed claim URL to the user. - Prefer `push` for existing linked directories and `create` for new directories. - Ask before using `--public` or `--visibility public`; workspace visibility is the default. - Do not run `hunk login` unless the user asks for an authenticated CLI session. - Ask before using `--force`; it creates a separate hunk instead of updating the existing link. - Fix invalid `.hunk/config.json` fields instead of editing around validation errors; `hunk.id` must be a non-empty string. - Ask before deleting; `hunk delete --yes` permanently deletes the remote hunk and deployments. - Do not commit `.hunk/config.json` unless the user wants the hunk link tracked in version control. ## Errors All command failures exit non-zero. Many API errors include JSON with `code` and `message`. Common recovery: | Error or symptom | Cause | Recovery | | ------------------------------------------ | ------------------------------------------ | ---------------------------------------------------------- | | Hunk is waiting for browser login | User has not opened the claim URL yet | Give the claim URL to the user and retry after claim | | Not authenticated | A non-create command needs a claimed hunk | Ask the user to claim the hunk or provide auth | | Missing `index.html` | Target directory is not a static site root | Ask the user which folder to publish | | Existing `.hunk/config.json` during create | Directory is already linked | Use `hunk push`, or ask before `hunk create --force` | | Invalid `.hunk/config.json` | Local hunk config failed schema validation | Fix the reported field, or use `create --force` to replace | | Push cannot find hunk config | Directory is not linked | Run `hunk create` first | | Page does not auto-reload after updates | Events script is missing from `` | Add `` and push | | Delete rejected | Missing confirmation flag | Only rerun with `--yes` after explicit user confirmation | ## Further Docs - Hunk: https://hunk.851.sh - Hunk app: https://app.hunk.851.sh - CLI package: https://www.npmjs.com/package/@851-labs/hunk