Skip to main content
skill CX Codex

skillshare-devcontainer — Claude Code skill: tests in devcontainer

skillshare-devcontainer runs the skillshare CLI, Go tests and the web dashboard inside the project's devcontainer, so macOS never silently mangles a command.

MIT ★ 3,269 updated 2026-10-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add runkids/skillshare --skill skillshare-devcontainer -a claude-code
Open on GitHub

What skillshare-devcontainer does

The skill keeps every run inside the devcontainer: the ss and skillshare CLI, go test, make test, make check, and starting the dashboard. Why bother? The host is macOS while the project binary is built for Linux, so the same command on the host fails or returns quietly wrong output. Before acting, the skill runs python3 scripts/ai-context.py testing and treats that topic as the rulebook for how tests are executed.

Source is bind-mounted at /workspace. The ss wrapper rebuilds on each call, so editing a file on the host and then running docker exec $CONTAINER ss <command> is enough, with no make build and no restart. For flows that touch config (init, install, sync), ssenv hands out isolated HOME directories under ~/.ss-envs/<name>/ so the container's default state stays clean.

make devc builds, initialises and drops you into a shell; make devc-up, make devc-down and make devc-reset cover the rest of the lifecycle. docker exec $CONTAINER ui starts the dashboard on http://localhost:45173, with logs in /tmp/api-dev.log and /tmp/vite-dev.log. Editing code and git stay on the host, and end-to-end runbooks belong to the separate cli-e2e-test skill.

What it helps with

  • run Go unit and integration tests in a Linux container
  • check ss install against a clean HOME with ssenv
  • reproduce a bug report in an isolated environment
  • start the dashboard and read the API and Vite logs
  • confirm a source edit is picked up without rebuilding

Example prompts for the agent

  • Run make test inside the devcontainer and summarise the failures
  • Spin up a fresh ssenv and try ss install runkids/demo-skills there
  • Start the web UI in the container and tail /tmp/api-dev.log

How to install skillshare-devcontainer

1Skills CLI (Vercel)

npx skills add runkids/skillshare --skill skillshare-devcontainer -a claude-code

2Manually: put the files in place

~/.claude/skills/skillshare-devcontainer/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/skillshare-devcontainer/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about skillshare-devcontainer

How do I install skillshare-devcontainer in Claude Code?

Run npx skills add runkids/skillshare --skill skillshare-devcontainer -a claude-code. The skill lands in ~/.claude/skills/skillshare-devcontainer/SKILL.md.

What does skillshare-devcontainer do?

It runs the skillshare CLI, its tests and the web UI inside the devcontainer. It first reads python3 scripts/ai-context.py testing and follows the rules from that topic.

Why can't I just run the commands on my host?

The host is macOS and the project binary targets Linux, so a command on the host either fails or gives wrong output with no error. Route it through docker exec into the container.

Source text

SKILL.md · MIT
---
name: skillshare-devcontainer
description: >-
  Run CLI commands, tests, and debugging inside the skillshare devcontainer.
  Use this skill whenever you need to: execute skillshare CLI commands for
  verification, run Go tests (unit or integration), reproduce bugs, test new
  features, start the web UI, or perform any operation that requires a Linux
  environment. All CLI execution MUST happen inside the devcontainer — never
  run skillshare commands on the host. If you are about to use Bash to run
  `ss`, `skillshare`, `go test`, or `make test`, stop and use this skill
  first to ensure correct container execution.
argument-hint: "[command-to-run | task-description]"
metadata: 
  targets: [claude, universal]
---

Execute CLI commands and tests inside the devcontainer. The host machine is macOS but the project binary is Linux — running CLI commands on the host will silently produce wrong results or fail. This skill prevents that mistake.

Before acting, run `python3 scripts/ai-context.py testing` and follow that topic. The topic is the source of truth for repository execution boundaries and test rules; this skill retains the interactive workflow and command recipes.

## When to Use This

- Running `ss` / `skillshare` commands for verification
- Running `go test`, `make test`, `make check`
- Reproducing a bug report
- Testing a feature you just implemented
- Starting the web UI dashboard
- Any command that needs the skillshare binary or Go toolchain

## When NOT to Use This

- Editing source code (do that on host via Read/Edit tools)
- Running `git` commands (git works on host)
- Running `make fmt`, `make lint` (host-safe Go toolchain commands; no container needed)
- E2E test runbooks → use `cli-e2e-test` skill instead (it handles ssenv isolation)

## Architecture: Two Layers of Isolation

```
Host (macOS)
  └─ Devcontainer (Linux, Debian-based)
       ├─ Default HOME: /home/developer (persistent volume)
       ├─ Source: /workspace (bind-mount of repo root)
       └─ ssenv environments: ~/.ss-envs/<name>/ (isolated HOME dirs)
```

**Devcontainer** = Linux environment with Go, git, pnpm, air (hot-reload). Source code is at `/workspace` (bind-mount of the host repo). The `ss` / `skillshare` wrapper auto-builds from source on every invocation — **no manual `make build` needed**. Edit code on the host, then immediately `docker exec` to run it; the change is picked up automatically.

**ssenv** = Isolated HOME directories within the devcontainer. Each env gets its own `~/.config/skillshare/`, `~/.claude/`, etc. Use ssenv when you need a clean state (testing init, install, sync) without polluting the container's default HOME.

## Zero-Rebuild Workflow

Source code is bind-mounted into the container at `/workspace`. The `ss` wrapper runs `go build` transparently on every invocation:

1. Edit files on host (Read/Edit tools)
2. `docker exec $CONTAINER ss <command>` — picks up your changes instantly
3. No `make build`, no restart, no rebuild step

This also applies to `go test` — tests always compile against the latest source. The Web UI backend uses `air` for hot-reload (same zero-rebuild experience).

## Entering the Devcontainer

The quickest way — one command builds, initialises, and enters the shell:

```bash
make devc           # build + init + interactive shell (one step)
make devc-up        # start only (no shell)
make devc-down      # stop
make devc-restart   # restart + re-run start-dev.sh
make devc-reset     # full reset (remove volumes), then `make devc` to re-init
make devc-status    # show container status
```

Works with **or without** VS Code — `make devc` handles the full lifecycle autonomously.

### Programmatic access (for `docker exec` workflows)

```bash
CONTAINER=$(docker compose -f .devcontainer/docker-compose.yml ps -q skillshare-devcontainer 2>/dev/null)
```

If `$CONTAINER` is empty, tell the user:
> Devcontainer is not running. Start it with `make devc-up`.

Then verify the binary:
```bash
docker exec $CONTAINER bash -c \
  '/workspace/.devcontainer/ensure-skillshare-linux-binary.sh && ss version'
```

## Running Commands

### Simple command (uses container's default HOME)

```bash
docker exec $CONTAINER ss <command> [flags]
```

Good for: `ss version`, `ss status`, `ss list`, `ss check`, `ss audit`.

### Command with isolated HOME (clean state)

```bash
ENV_NAME="test-$(date +%s)"
docker exec $CONTAINER ssenv create "$ENV_NAME" --init
docker exec $CONTAINER ssenv enter "$ENV_NAME" -- ss status
# Cleanup when done:
docker exec $CONTAINER ssenv delete "$ENV_NAME" --force
```

Good for: testing `init`, `install`, `sync`, `uninstall` — anything that modifies config/state.

### Multi-command sequence

```bash
docker exec $CONTAINER ssenv enter "$ENV_NAME" -- bash -c '
  ss install runkids/demo-skills --track --force
  ss list
  ss sync
'
```

Always use `bash -c '...'` for multi-command sequences inside `ssenv enter`.

### Go tests

```bash
# All tests (unit + integration)
docker exec $CONTAINER bash -c 'cd /workspace && make test'

# Unit tests only
docker exec $CONTAINER bash -c 'cd /workspace && make test-unit'

# Integration tests only
docker exec $CONTAINER bash -c 'cd /workspace && make test-int'

# Specific test
docker exec $CONTAINER bash -c 'cd /workspace && go test ./tests/integration -run TestInit_Fresh -count=1'

# Specific package
docker exec $CONTAINER bash -c 'cd /workspace && go test ./internal/install/... -count=1'
```

Always `cd /workspace` before Go commands — ssenv changes HOME which can break module resolution.

### Go tests with auth disabled

Token-resolution tests (`TestResolveToken`, `TestAuthEnv` in `internal/install`) need auth credentials removed:

```bash
docker exec $CONTAINER bash -lc '
  eval "$(credential-helper --eval off)"
  cd /workspace
  go test ./internal/install -run "TestResolveToken|TestAuthEnv" -count=1
  eval "$(credential-helper --eval on)"
'
```

## Web UI Dashboard

```bash
# Start (global mode)
docker exec $CONTAINER ui

# Start (project mode — uses ~/demo-project)
docker exec $CONTAINER ui -p

# Stop
docker exec $CONTAINER ui stop
```

Dashboard accessible at `http://localhost:45173` (Vite dev server with HMR).
API backend at `http://localhost:49420`.
Logs: `/tmp/api-dev.log`, `/tmp/vite-dev.log`.

## ssenv Quick Reference

| Shortcut | Full form | Purpose |
|----------|-----------|---------|
| `ssnew <name>` | `ssenv create <name>` + enter | Create and enter isolated shell |
| `ssuse <name>` | `ssenv enter <name>` | Enter existing isolated shell |
| `ssrm <name>` | `ssenv delete <name> --force` | Delete environment |
| `ssls` | `ssenv list` | List all environments |
| `ssback` | `ssenv reset` | Leave isolated context |
| `sshelp` | `help` | Show all devcontainer commands |

For automation (non-interactive), prefer `ssenv enter <name> -- <command>` over `ssnew`/`ssuse` (which launch subshells).

## Ports

| Port | Service | Notes |
|------|---------|-------|
| 45173 | Vite dev server | React dashboard with HMR |
| 49420 | Go API backend | `skillshare ui` server |
| 48888 | Docusaurus | `docs` command in devcontainer |

## Common Mistakes to Avoid

1. **Running `ss` on host** — macOS binary won't match Linux container; always `docker exec`
2. **Forgetting `cd /workspace`** — Go tests fail if HOME was changed by ssenv
3. **Using `make test` on host** — builds macOS binary, then tests run against wrong arch
4. **Skipping `--init` on ssenv create** — env won't have config; most commands will fail
5. **Not cleaning up ssenv** — `ssenv delete <name> --force` after done; or ask user
6. **Running from /workspace root without -g** — the `ss` wrapper auto-redirects to `~/demo-project` in project mode; use `-g` for global or set `SKILLSHARE_DEV_ALLOW_WORKSPACE_PROJECT=1`
7. **Running `make build` before testing** — unnecessary; the `ss` wrapper auto-builds from source every time

## Rules

Apply the `testing` topic. If a command recipe here conflicts with that topic or current repo configuration, verify the current configuration and update both in the same change.

© runkids · MIT · runkids/skillshare

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set10

The whole set →
skillshare-code-review skillshare-code-review is a Claude Code skill that reviews changes in skillshare before a pull request or after one opens. It starts on requests to inspect a diff, branch, commit range, or PR. CX Codex +1 ★ 3,269repo stars skillshare-changelog skillshare-changelog turns the commits between two tags into a CHANGELOG.md entry and copies it to the project's website changelog page. CX Codex +1 ★ 3,269repo stars skillshare-windows-utm skillshare-windows-utm is a Claude Code skill that tests skillshare in a local UTM Windows guest, building pinned commits in a devcontainer and checking symlinks, junctions, and copy fallbacks. CX Codex +1 ★ 3,269repo stars skillshare-implement-feature The skillshare-implement-feature skill takes a Go feature from a spec or plain description through TDD and verification. Use it for CLI commands, flags, and internal packages. CX Codex +1 ★ 3,269repo stars skillshare-release Coordinates and verifies skillshare releases through Release Please PRs, syncs documentation across locales, and inspects draft assets. CX Codex +1 ★ 3,269repo stars skillshare This skill guides Skillshare CLI workflows for syncing resources, checking configuration, and managing shared memory. Use it when setting up a project or user-wide environment. CX Codex +1 ★ 3,269repo stars skillshare-ui-website-style skillshare-ui-website-style keeps the Skillshare design system in place across a React dashboard and a Docusaurus site. Useful when you touch styles or add a component and want it to match. CX Codex +1 ★ 3,269repo stars skillshare-cli-e2e-test skillshare-cli-e2e-test executes isolated CLI E2E test runbooks inside a devcontainer using mdproof reporting. CX Codex +1 ★ 3,269repo stars

Project sponsors

Companies that keep this analytics open