# SkillHub Offline Usage Guide

This guide covers the supported offline workflows:

1. Deploy SkillHub in an intranet.
2. Load the official Dockerized `clawhub` CLI.
3. Load and publish offline skill packs.
4. Build new offline packs on an internet-connected machine.
5. Troubleshoot common failures.

## 1. Directory Layout

Important files:

- `.env.release`: deployment environment variables.
- `docker-compose.yaml`: SkillHub stack.
- `images/skillhub-images-v0.2.8.tar`: offline service images.
- `images/clawhub-cli-latest.tar`: official `clawhub` CLI Docker image.
- `artifacts/devops-testing-skills-offline-20260605.tar.gz`: curated dev/ops/test skill pack.
- `artifacts/github-skills-offline-20260605.tar.gz`: broad GitHub skill pack.
- `scripts/load-offline-skill-pack.sh`: generic skill-pack loader.
- `scripts/deploy-offline-skills.sh`: Docker-based batch publisher.

## 2. Deploy SkillHub

Copy the package to the intranet host:

```bash
sudo mkdir -p /opt/skillhub
sudo cp -r . /opt/skillhub/
cd /opt/skillhub
```

Review and edit `.env.release`:

```bash
vi .env.release
```

At minimum, set:

- `SKILLHUB_PUBLIC_BASE_URL`
- `POSTGRES_PASSWORD`
- `BOOTSTRAP_ADMIN_PASSWORD`

Load images and start:

```bash
bash scripts/load-images.sh
docker compose --env-file .env.release -f docker-compose.yaml up -d
docker compose --env-file .env.release -f docker-compose.yaml ps
```

Check backend health:

```bash
curl -fsS http://127.0.0.1:8080/actuator/health
```

## 3. Load Official ClawHub CLI Docker Image

The batch publisher uses the official npm `clawhub` CLI inside Docker. Load it:

```bash
bash scripts/load-clawhub-cli-image.sh images/clawhub-cli-latest.tar
```

Verify:

```bash
docker run --rm skillhub/clawhub-cli:latest --cli-version
```

Expected version in this package:

```text
0.19.1
```

## 4. Publish The Dev/Ops/Test Pack

Load the pack:

```bash
bash scripts/load-offline-skill-pack.sh artifacts/devops-testing-skills-offline-20260605.tar.gz
```

Publish from the tarball:

```bash
CLAWHUB_REGISTRY=http://127.0.0.1:8080 \
CLAWHUB_TOKEN=your-api-token \
bash scripts/deploy-offline-skills.sh artifacts/devops-testing-skills-offline-20260605.tar.gz
```

Or publish from the unpacked directory:

```bash
CLAWHUB_REGISTRY=http://127.0.0.1:8080 \
CLAWHUB_TOKEN=your-api-token \
bash scripts/deploy-offline-skills.sh seed-skills/devops-testing
```

Use the public intranet host instead of `127.0.0.1` if running from another
machine:

```bash
CLAWHUB_REGISTRY=http://skillhub.intra.example.com:8080
```

## 5. Publish Only One Namespace

The dev/ops/test pack includes these namespaces:

- `dev-tools`
- `dev-anthropic`
- `dev-community`
- `dev-office`
- `dev-nvidia`

Publish one namespace:

```bash
ONLY_NAMESPACE=dev-community \
CLAWHUB_REGISTRY=http://127.0.0.1:8080 \
CLAWHUB_TOKEN=your-api-token \
bash scripts/deploy-offline-skills.sh seed-skills/devops-testing
```

## 6. Publish The Broad GitHub Pack

Load:

```bash
bash scripts/load-offline-skill-pack.sh artifacts/github-skills-offline-20260605.tar.gz
```

Publish:

```bash
CLAWHUB_REGISTRY=http://127.0.0.1:8080 \
CLAWHUB_TOKEN=your-api-token \
bash scripts/deploy-offline-skills.sh artifacts/github-skills-offline-20260605.tar.gz
```

This pack is broader and more likely to trigger pre-publish warnings. Review:

```bash
less reports/github-skill-import-report.md
```

## 7. Warning Handling

SkillHub may reject a publish attempt with:

```text
Pre-publish warnings require confirmation before publishing
```

The batch script default is:

```bash
ON_PUBLISH_WARNING=skip
```

This skips the blocked skill and continues. Details are written to:

```text
reports/offline-publish-skipped-warnings.log
```

Strict mode:

```bash
ON_PUBLISH_WARNING=fail \
CLAWHUB_REGISTRY=http://127.0.0.1:8080 \
CLAWHUB_TOKEN=your-api-token \
bash scripts/deploy-offline-skills.sh seed-skills/devops-testing
```

## 8. Build Artifacts On An Internet-Connected Machine

Build the official CLI image tar:

```bash
bash scripts/build-clawhub-cli-image.sh
```

Outputs:

- `images/clawhub-cli-latest.tar`
- `images/clawhub-cli-latest.tar.sha256`

Build the broad GitHub pack:

```bash
bash scripts/build-github-skill-offline-pack.sh
```

Build the curated dev/ops/test pack:

```bash
bash scripts/build-devops-testing-skill-pack.sh
```

Build the SkillHub service images:

```bash
bash scripts/pull-save-images.sh
```

## 9. Environment Variables

Publisher variables:

- `CLAWHUB_REGISTRY`: SkillHub API base URL.
- `CLAWHUB_SITE`: SkillHub public site URL. Defaults to `CLAWHUB_REGISTRY`.
- `CLAWHUB_TOKEN`: API token used by official `clawhub login --token`.
- `CLAWHUB_CLI_IMAGE`: Docker image to run. Default: `skillhub/clawhub-cli:latest`.
- `ONLY_NAMESPACE`: publish one namespace only.
- `PUBLISH_TAGS`: tags passed to official `clawhub publish`. Default: `latest`.
- `ON_PUBLISH_WARNING`: `skip` or `fail`. Default: `skip`.
- `CLAWHUB_DOCKER_CONFIG_DIR`: host directory for the official CLI config.

## 10. Troubleshooting

### `Offline pack does not contain seed-skills/github`

You are using old scripts that only support the broad GitHub pack. Use the
current generic scripts:

```bash
bash scripts/load-offline-skill-pack.sh artifacts/devops-testing-skills-offline-20260605.tar.gz
bash scripts/deploy-offline-skills.sh artifacts/devops-testing-skills-offline-20260605.tar.gz
```

### `Client id must not be empty`

The server received empty OAuth client IDs. Use the current `docker-compose.yaml`
from this package, which provides non-empty placeholders for unused OAuth
providers.

### Docker CLI image is missing

Load it:

```bash
bash scripts/load-clawhub-cli-image.sh images/clawhub-cli-latest.tar
```

Then verify:

```bash
docker run --rm skillhub/clawhub-cli:latest --help
```

### Backend health check fails

Check containers:

```bash
docker compose --env-file .env.release -f docker-compose.yaml ps
docker compose --env-file .env.release -f docker-compose.yaml logs --tail=200 server
```

Check the API URL:

```bash
curl -v http://127.0.0.1:8080/actuator/health
```

Set the right registry:

```bash
export CLAWHUB_REGISTRY=http://127.0.0.1:8080
```

### Pre-publish warnings

Review:

```bash
less reports/offline-publish-skipped-warnings.log
```

Clean the flagged skill content, then republish the relevant namespace or skill.

## 11. Expose SkillHub At `/skillhub`

DNS can only point `ipd.abc.com` to an IP address. The `/skillhub` part is a URL
path prefix, so it must be handled by an external reverse proxy.

Recommended `.env.release` changes:

```bash
SKILLHUB_PUBLIC_BASE_URL=http://ipd.abc.com/skillhub
SKILLHUB_WEB_API_BASE_URL=/skillhub/api

WEB_PORT=18080
API_PORT=18081
SESSION_COOKIE_SECURE=false
```

Restart SkillHub after changing `.env.release`:

```bash
docker compose --env-file .env.release -f docker-compose.yaml up -d --force-recreate server web
```

Install the external Nginx config:

```bash
sudo cp config/nginx-skillhub-subpath.conf /etc/nginx/conf.d/skillhub.conf
sudo nginx -t
sudo systemctl reload nginx
```

Then access:

```text
http://ipd.abc.com/skillhub
```

For CLI publishing through this URL, use:

```bash
CLAWHUB_REGISTRY=http://ipd.abc.com/skillhub \
CLAWHUB_SITE=http://ipd.abc.com/skillhub \
CLAWHUB_TOKEN=your-api-token \
bash scripts/deploy-offline-skills.sh seed-skills/devops-testing
```

If you can choose a subdomain instead, `http://skillhub.ipd.abc.com` is simpler
and more robust than a path prefix because the current frontend image is built
for root-path static assets.