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
npx skills add runkids/skillshare --skill skillshare-devcontainer -a claude-codeWhat 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 installagainst 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 testinside the devcontainer and summarise the failures - Spin up a fresh ssenv and try
ss install runkids/demo-skillsthere - 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-code2Manually: put the files in place
~/.claude/skills/skillshare-devcontainer/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/skillshare-devcontainer/
1Skills CLI (Vercel)
npx skills add runkids/skillshare --skill skillshare-devcontainer -a codex2Manually: put the files in place
.agents/skills/skillshare-devcontainer/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add runkids/skillshare --skill skillshare-devcontainer -a cursor2Manually: put the files in place
.cursor/skills/skillshare-devcontainer/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install runkids/skillshare .skillshare/skills/skillshare-devcontainer2Manually: put the files in place
.github/skills/skillshare-devcontainer/SKILL.md1Skills CLI (Vercel)
npx skills add runkids/skillshare --skill skillshare-devcontainer -a gemini-cli2Platform CLI
gemini skills install https://github.com/runkids/skillshare --path .skillshare/skills/skillshare-devcontainerManually: put the files in place
.devin/skills/skillshare-devcontainer/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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