feat: publish Crabbox sandbox quickstart for skills.sh

.agents/skills/crabbox-quickstart/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: crabbox-quickstart
+description: "First contact with Crabbox: run your repository's tests inside a disposable Docker or Podman container on your own machine, no account and no cloud spend, then stop the box. Use when someone asks what Crabbox is or how to try it, wants a throwaway sandbox for a repo with no crabbox.yaml yet, or is about to run crabbox init here; hand off to the crabbox skill for config that already exists, leased remote machines, jobs, secrets, or artifacts."
+license: MIT
+---
+
+# Crabbox Quickstart
+
+Crabbox runs your repository's commands on a disposable box — a container on
+your own machine, or a remote machine you lease. It syncs your working tree,
+runs one command, streams the output back, and exits with that command's code.
+
+## The loop
+
+```text
+lease -> sync -> run -> read output -> stop
+```
+
+- **Lease** a box from a provider. `--provider local-container` uses Docker or
+  Podman on your own machine: no account, no login, no spend.
+- **Sync** your current checkout onto it. Crabbox builds the file list from
+  Git, so the directory must be a repository.
+- **Run** one command there. Its exit code becomes Crabbox's exit code.
+- **Read** the streamed output, and optionally timing and test-result files.
+- **Stop** the box. A one-shot `run` does this for you; a warm box does not.
+
+## Install and check
+
+```sh
+crabbox --version                  # already installed? skip the install
+brew install openclaw/tap/crabbox  # or github.com/openclaw/crabbox/releases
+crabbox doctor --provider local-container
+```
+
+`doctor` with a provider is the readiness check that matters: it names the
+container runtime, the leases you already hold, and the `image=` your commands
+will run inside.
+
+## First run, no account needed
+
+With Docker or Podman running, this works in any Git repository with no config
+file, no login, and no cloud spend:
+
+```sh
+git init                                  # only if not already a repository
+crabbox run --provider local-container -- uname -a
+```
+
+Crabbox provisioned a container, synced the dirty checkout, ran the command
+there, streamed its output, propagated its exit code, and deleted the lease.
+Budget 30-45 seconds once the base image is local, nearly all of it container
+startup; the very first run adds a one-time image pull.
+
+## The box is bare
+
+Read this before swapping `uname -a` for real work. The default image is plain
+Ubuntu with `git`, `curl`, `tar`, `python3`, `rsync`, and passwordless `sudo`.
+No node, npm, make, gcc, go, cargo, or java. A command needing a runtime fails
+before your code does — usually exit 127 and `make: not found`, or for npm a
+preflight that stops the run first. Install what you need once, on a warm box:
+
+```sh
+crabbox warmup --provider local-container          # prints the <slug>
+crabbox run --provider local-container --id <slug> -- \
+  sudo apt-get install -y make
+```
+
+Your argv runs through a shell on the box, so `&&`, pipes, and redirects work.
+Making the setup permanent is a `.crabbox.yaml` job — that is the `crabbox`
+skill, not this page.
+
+## Warm a box and reuse it
+
+One-shot runs pay for container startup every time, and throw away whatever
+you installed. Keep one box and send several commands to it instead:
+
+```sh
+crabbox warmup --provider local-container
+crabbox run --provider local-container --id <slug> -- ./run-tests.sh
+crabbox status --provider local-container --id <slug>
+```
+
+`warmup` prints both a `cbx_...` lease id and a friendly slug; either works as
+`--id`. A cold run measured 33-45 seconds, the same run warm about 4 seconds.
+Above and below, `./run-tests.sh` stands for your own test command.
+
+## What actually gets synced
+
+Your dirty working tree filtered by Git, not a committed ref, so
+untracked-but-not-ignored files do get uploaded — minus a built-in exclude
+list: `node_modules`, `dist`, `target`, `.venv`, `__pycache__`, and other
+dependency and build output. That never travels; rebuild it in the box.
+`crabbox sync-plan` prints the file count, total bytes, and the largest files
+and directories without starting a container. Exclude anything else surprising
+in `.crabboxignore`.
+
+## Errors you will meet first
+
+Exit 2 is a missing `--provider`, 6 a directory that is not a Git repository,
+7 a runtime Crabbox cannot reach, 4 an `--id` naming no live lease. Your own
+command's code passes through verbatim too, so the number alone never says
+which failed — read the message, then rerun the `doctor` command above.
+
+When your command itself fails, Crabbox exits with its code, prints a
+failure digest with `next:` commands, and drops a bundle in
+`.crabbox/captures/`. Sync excludes it; add `.crabbox/` to `.gitignore`.
+
+## Environment and secrets
+
+Nothing from your shell crosses into the box automatically; forwarding is an
+allowlist by name, set with `--allow-env` or `env.allow` in the repo config.
+Never put a token on a command line; the `crabbox` skill covers the rest.
+
+## Evidence from a run
+
+Evidence flags attach to any `run` and cost no extra time:
+
+```sh
+crabbox run --provider local-container --results-auto -- ./run-tests.sh
+```
+
+If your command writes a JUnit XML report, `--results-auto` finds it without
+being told the path and summarizes it in one line:
+
+```text
+test results files=1 tests=3 failures=1 errors=0 skipped=1
+```
+
+If nothing writes a JUnit file the flag is a silent no-op.
+
+## Stop what you started
+
+Boxes from `warmup` outlive the command; so do runs given `--keep`. Stop them:
+
+```sh
+crabbox stop <slug>
+crabbox list --provider local-container
+```
+
+An empty `list` means no leases remain on that provider. Local containers kept
+by `warmup` or `--keep` require explicit `stop`; they do not expire on their own.
+
+## When you outgrow this page
+
+Stop here and load the full `crabbox` skill as soon as the task involves any of:
+
+- a repository that already has `crabbox.yaml` or `.crabbox.yaml`, including
+  one `crabbox init --detect` has just written
+- any provider other than `local-container`, or a broker login
+- a toolchain the base image lacks that you want present on every run
+- named jobs, pools, prewarming, a fresh PR checkout, or Windows targets
+- environment or secret forwarding, artifacts, or desktop and UI proof
+- a failure that `crabbox doctor` output does not explain

.github/workflows/pages.yml

@@ -6,7 +6,7 @@ on:
       - main
     paths:
       - "docs/**"
-      - "skills/crabbox/**"
+      - "skills/**"
       - "scripts/build-docs-site.mjs"
       - "scripts/enhance-docs-site.mjs"
       - "scripts/normalize-provider-counts.mjs"

README.md

@@ -181,27 +181,37 @@ tracked in https://github.com/openclaw/crabbox/issues/1157. See the [integration
 catalog](docs/integrations/README.md) for current support and lifecycle
 boundaries.
 
-Existing repositories that only need agent discovery can install the generic
-Skill with GitHub CLI:
+Repositories that only need agent discovery can install Crabbox's published
+Agent Skills with GitHub CLI:
 
 ```sh
 gh skill install openclaw/crabbox skills/crabbox \
   --pin refs/heads/main --agent codex --scope project
+gh skill install openclaw/crabbox skills/crabbox-quickstart \
+  --pin refs/heads/main --agent codex --scope project
 ```
 
-Or use the cross-client Skills CLI:
+Or install the sandbox execution skill with the [skills.sh](https://skills.sh) CLI:
 
 ```sh
-npx skills add https://github.com/openclaw/crabbox --skill crabbox
+npx skills add openclaw/crabbox --skill crabbox
+npx skills add openclaw/crabbox --skill crabbox-quickstart
 ```
 
+Choose `crabbox` for sandbox execution and remote testing, or
+`crabbox-quickstart` for a first local Docker/Podman run. Skills teach your agent
+how to use Crabbox; install the CLI separately using the instructions above.
+See the [skill installation guide](docs/integrations/agents.md#install-through-ecosystem-skill-managers)
+for discovery and supported clients.
+
 Crabbox also publishes a digest-verified discovery index from its own domain:
 
 ```sh
 npx skills add https://crabbox.sh --skill crabbox
+npx skills add https://crabbox.sh --skill crabbox-quickstart
 ```
 
-Cross-vendor discovery services can index the same Skill through Crabbox's
+Cross-vendor discovery services can index both Skills through Crabbox's
 [draft-compatible AI Catalog](https://crabbox.sh/.well-known/ai-catalog.json).
 
 Herdr users can add Crabbox lease controls and repository workflows to the

docs/getting-started.md

@@ -9,7 +9,11 @@ Read this when:
 This is a cookbook, not a reference. It walks through one repo from install to
 `crabbox run -- pnpm test`. Each step links to deeper docs when you want more.
 If you are still deciding whether Crabbox fits your workflow, start with
-[What Crabbox is](README.md#what-crabbox-is).
+[What Crabbox is](README.md#what-crabbox-is). For a first run with no account
+at all, `--provider local-container` executes against Docker or Podman on your
+own machine; the
+[`crabbox-quickstart` skill](integrations/agents.md#install-through-ecosystem-skill-managers)
+walks that credential-free path end to end.
 
 ## Step 1. Install
 

docs/integrations/README.md

@@ -18,6 +18,7 @@ or marketplace, even when they consume Crabbox.
 | Goal | Surface | Status |
 | --- | --- | --- |
 | Teach a local coding agent when and how to use Crabbox | [`crabbox init` Agent Skill](agents.md#local-agent-clients) | Available |
+| Give a coding agent the shortest path from install to a first successful run | [`crabbox-quickstart` skill](agents.md#install-through-ecosystem-skill-managers) | Available |
 | Run a repo-owned one-shot harness remotely | [`crabbox run` or a named job](agents.md#one-shot-harnesses) | Credential-free run-evidence pattern available |
 | Reuse repository setup on a warm lease | [GitHub Actions hydration](../features/actions-hydration.md) | Available |
 | Use Zed as a local Crabbox control surface | [Zed extension package](editors.md#zed-control-surface) | Package available; [registry submission not yet opened](https://github.com/openclaw/crabbox/issues/1157) |

docs/integrations/agents.md

@@ -97,50 +97,70 @@ required `name` and `description` frontmatter manually.
 
 ### Install through ecosystem skill managers
 
-Crabbox also publishes its generic Skill at the non-hidden
-`skills/crabbox/SKILL.md` ecosystem installer convention. This makes the
-authoritative generic Skill visible to installers instead of requiring them to
-search Crabbox's repo-local `.agents` projection.
+Crabbox also publishes its generic Skills at the non-hidden
+`skills/<name>/SKILL.md` ecosystem installer convention. This makes the
+authoritative generic Skills visible to installers instead of requiring them to
+search Crabbox's repo-local `.agents` projection. Two ship today:
+
+- **`crabbox`** (`skills/crabbox`): run repository commands in sandbox
+  environments, reuse remote machines, and collect execution evidence.
+- **`crabbox-quickstart`** (`skills/crabbox-quickstart`): get from CLI
+  installation to a first disposable local-container run and explicit cleanup.
+
+Install `crabbox-quickstart` for first contact, or when the repository has no
+`crabbox.yaml` yet; it hands off to `crabbox` as soon as a task needs a
+provider login, a named job, secrets, or artifacts. Install both when
+newcomers and regular users share a repository.
 
 GitHub CLI 2.90 or newer maps Agent Skills into many host-specific locations:
 
 ```sh
 gh skill install openclaw/crabbox skills/crabbox \
   --pin refs/heads/main --agent codex --scope project
+gh skill install openclaw/crabbox skills/crabbox-quickstart \
+  --pin refs/heads/main --agent codex --scope project
 ```
 
 Replace `codex` with the target reported by `gh skill install --help`. The
-cross-client Skills CLI can install the same source and prompt for a target:
+cross-client Skills CLI can install the same sources and prompt for a target:
 
 ```sh
 npx skills add https://github.com/openclaw/crabbox --skill crabbox
+npx skills add https://github.com/openclaw/crabbox --skill crabbox-quickstart
 ```
 
-The generic source has an [official-repository skills.sh
-listing](https://www.skills.sh/openclaw/crabbox/crabbox).
-The checked-in `skills/crabbox` source and `.agents/skills/crabbox` projection
-are byte-identical and CI rejects drift. Use `crabbox init` when the repository
-also needs Crabbox configuration, Actions hydration, and detected project-job
-instructions; use a skill manager when only agent discovery is missing.
+These are the GitHub sources used by [skills.sh](https://skills.sh). Its
+[leaderboard discovers skills through CLI installation telemetry](https://skills.sh/docs/faq);
+publishing a domain discovery index alone does not submit a listing.
+Use `npx skills add openclaw/crabbox --list` to check available skills.
+Installing a skill adds agent instructions; install the Crabbox CLI separately
+to create and run sandboxes.
+Every checked-in `skills/<name>` source and its `.agents/skills/<name>`
+projection are byte-identical and CI rejects drift. Use `crabbox init` when the
+repository also needs Crabbox configuration, Actions hydration, and detected
+project-job instructions; use a skill manager when only agent discovery is
+missing.
 `--pin refs/heads/main` selects this unreleased branch explicitly; after 0.40.0
 is tagged, omit it to follow GitHub CLI's latest-release resolution.
 
 ### Discover from crabbox.sh
 
-The docs build publishes the same Skill with a content digest through
+The docs build publishes the same Skills with content digests through
 Cloudflare's [draft Agent Skills discovery
 protocol](https://github.com/cloudflare/agent-skills-discovery-rfc):
 
 - `https://crabbox.sh/.well-known/agent-skills/index.json`
 - `https://crabbox.sh/.well-known/agent-skills/crabbox/SKILL.md`
+- `https://crabbox.sh/.well-known/agent-skills/crabbox-quickstart/SKILL.md`
 
-The index declares the draft 0.2.0 schema and a SHA-256 digest of the exact
+The index declares the draft 0.2.0 schema and a SHA-256 digest of each exact
 published `SKILL.md`. Clients that implement domain discovery can therefore
 find and verify Crabbox without a GitHub-specific registry. After the next docs
 deployment, the Skills CLI can consume the same endpoint directly:
 
 ```sh
 npx skills add https://crabbox.sh --skill crabbox
+npx skills add https://crabbox.sh --skill crabbox-quickstart
 ```
 
 Domain discovery is an emerging transport, not part of the core Agent Skills
@@ -158,9 +178,9 @@ https://crabbox.sh/.well-known/ai-catalog.json
 ```
 
 The catalog follows the draft [Agentic Resource Discovery
-specification](https://github.com/ards-project/ard-spec), identifies the
+specification](https://github.com/ards-project/ard-spec), identifies each
 artifact as `application/agent-skills+md`, and points to the same published
-`SKILL.md`. It includes representative queries for remote testing,
+`SKILL.md` files. It includes representative queries for remote testing,
 cross-platform validation, and auditable evidence so ARD-compatible discovery
 services can match Crabbox at task time. The site also advertises the catalog
 through an HTML `ai-catalog` link and an `Agentmap` directive in `robots.txt`.

docs/source-map.md

@@ -54,13 +54,14 @@ Crabbox has three implementation surfaces:
 - The catalog inventories Crabbox-hosted surfaces. Host-owned integrations are
   versioned and inventoried in their host repositories rather than duplicated
   in this source map.
-- Publishable generic Agent Skill: `skills/crabbox/SKILL.md`, with the
-  byte-identical repo-discovery projection at
-  `.agents/skills/crabbox/SKILL.md` and drift validation in
+- Publishable generic Agent Skills: `skills/crabbox/SKILL.md` for the remote
+  execution surface and `skills/crabbox-quickstart/SKILL.md` for the
+  getting-started path, each with a byte-identical repo-discovery projection
+  at `.agents/skills/<name>/SKILL.md` and per-skill drift validation in
   `scripts/check-agent-skills.mjs`. The docs builder publishes the same bytes
-  plus a SHA-256 digest at `/.well-known/agent-skills/` for domain discovery,
-  and advertises the artifact through `/.well-known/ai-catalog.json` for
-  Agentic Resource Discovery.
+  plus a SHA-256 digest per skill at `/.well-known/agent-skills/` for domain
+  discovery, and advertises the artifacts through `/.well-known/ai-catalog.json`
+  for Agentic Resource Discovery.
 - Generated repo-local Agent Skill: `internal/cli/init.go`, with onboarding
   behavior in `docs/commands/init.md`.
 - Versioned editor handoff and foreground lease activity: