Agent skill

vm-bootstrap

Linux VM bootstrap verification skill. MUST BE USED when setting up new VMs or verifying environment. Supports modes: check (warn-only), install (operator-confirmed), strict (CI-ready). Enforces Linux-only + mise as canonical; honors preference brew→npm (with apt fallback). Verifies required tools: mise, node, pnpm, python, poetry, gh, railway, bd, tmux, jq, rg. Handles optional tools as warnings: tailscale, playwright, docker, bv. Never prints/seeds secrets; never stores tokens in repo/YAML; Railway vars only for app runtime env. Safe on dirty repos (refuses and points to dirty-repo-bootstrap skill, or snapshots WIP branch). Keywords: vm, bootstrap, setup, mise, toolchain, linux, environment, provision, verify, new vm

View SKILL.md on GitHub Repository
Stars 0
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/stars-end/agent-skills/tree/master/vm-bootstrap

SKILL.md

Linux VM Bootstrap Verification

Verify and optionally install required tools for a standardized Linux development VM.

Modes

Mode Behavior Use Case
check Warn-only, never modifies Local DX entrypoint, agents
install Prompt before each install Interactive bootstrap
strict Exit non-zero on first missing required tool CI jobs

Required Tools

Tool Why Source Verify
git repo sync, PRs apt git --version
curl installers, API calls apt curl --version
jq parse JSON (Railway/GH) brew (apt fallback) jq --version
rg (ripgrep) fast search apt or brew rg --version
tmux multi-agent sessions apt or brew tmux -V
mise toolchain versions mise installer mise --version
python backend + scripts mise (per repo) mise exec -- python --version
poetry python deps pipx or mise poetry --version
node frontend + tooling mise (per repo) mise exec -- node --version
pnpm monorepo installs mise / corepack mise exec -- pnpm --version
gh PRs + auth brew gh --version && gh auth status
railway env/shell/deploy mise (@railway/cli) mise exec -- railway --version
bd Beads tasks Beads installer bd --version

Optional Tools (warn-only)

Tool Why Verify
bv Beads graph insights bv --version
playwright UI/E2E mise exec -- playwright --version
tailscale cross-VM networking tailscale status
docker Railway railway dev / local deps docker --version

Security Rules (MUST FOLLOW)

  1. Never print tokens to logs or stdout
  2. Never store secrets in YAML, .env files, or repo
  3. Railway vars are for app runtime only (not runner/gh/tailscale credentials)
  4. gh auth and railway login use interactive prompts or GitHub secrets

Dirty Repo Safety

Before running in install or strict mode:

  1. Check git status --porcelain
  2. If dirty:
    • In check mode: warn and continue
    • In install/strict mode: refuse and suggest:
      • Commit/stash changes first, OR
      • Use /dirty-repo-bootstrap skill to snapshot to WIP branch

Agent Identity (DX_AGENT_ID)

Recommended: Set DX_AGENT_ID for consistent agent identification across repos and sessions.

bash
# Add to ~/.bashrc, ~/.zshrc, or ~/.profile
export DX_AGENT_ID="$(hostname -s)-claude-code"

Format: <magicdns-host>-<platform> Examples: v2202509262171386004-claude-code, macmini-codex-cli

Why: Provides stable identity for git trailers, Agent Mail coordination, and multi-repo workflows.

Helper script:

bash
~/.agent/skills/scripts/get_agent_identity.sh

Status: P2, warn-only. Missing DX_AGENT_ID triggers warnings but doesn't block operations.

See DX_AGENT_ID.md for full specification and migration path.

Agent Guidance

When this skill is relevant:

  1. Detect OS is Linux (refuse on macOS/Windows with clear message)
  2. Run verification for each required tool
  3. In check mode: report status (✓/✗) for each tool
  4. In install mode: prompt before each install
  5. In strict mode: exit 1 on first missing required tool

Command Usage

bash
# Check mode (default, safe for agents)
./vm-bootstrap/check.sh
# or
./vm-bootstrap/verify.sh check

# Install mode (interactive, operator-confirmed)
./vm-bootstrap/install.sh

# Strict mode (CI)
./vm-bootstrap/verify.sh strict

Note: check.sh is a wrapper for verify.sh check. install.sh provides interactive tool installation following the LINUX_VM_BOOTSTRAP_SPEC phases.

Integration

DX entrypoints should call vm-bootstrap check as first step:

bash
# In scripts/bd-context or make dx-doctor
~/agent-skills/vm-bootstrap/verify.sh check

Related Skills

  • toolchain-health: Python-specific mise/Poetry alignment
  • mcp-doctor: MCP server health check
  • skills-doctor: Skills discovery and loading verification

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

stars-end/agent-skills

toolchain-health

Validate Python toolchain alignment between mise, Poetry, and pyproject. Use when changing Python versions, editing pyproject.toml, or seeing Poetry/mise version solver errors. Invokes /toolchain-health to check: - .mise.toml python tool version - pyproject.toml python constraint - Poetry env python interpreter Keywords: python version, mise, poetry, toolchain, env use, lock, install

0 0
Explore
stars-end/agent-skills

parallelize-cloud-work

Delegate independent work to Claude Code Web cloud sessions for parallel execution. Generates comprehensive session prompts with context exploration guidance, verifies Beads state, provides tracking commands. Use when user says "parallelize work to cloud", "start cloud sessions", or needs to execute multiple independent tasks simultaneously, or when user mentions cloud sessions, cloud prompts, delegate to cloud, Claude Code Web, generate session prompts, parallel execution, or asks "how do I use cloud sessions".

0 0
Explore
stars-end/agent-skills

docs-create

Create epic-specific documentation skill with external reference docs. MUST BE USED for caching external docs. Fetches URLs, caches full content, uses documentation-engineer to generate cohesive summaries, and creates auto-activating skill. Use when starting work on epic that requires external documentation context (API docs, tool guides, reference materials), or when user mentions "cache docs", "external docs", "API documentation", URLs for docs, documentation needs, reference materials, knowledge caching, or epic context documentation.

0 0
Explore
stars-end/agent-skills

railway-doctor

0 0
Explore
stars-end/agent-skills

git-safety-guard

Installs a Git safety guard hook for Claude Code to prevent destructive Git and filesystem commands. Blocks accidental data loss from commands like 'git checkout --', 'git reset --hard', 'git clean -f', 'git push --force', and 'rm -rf'. Use this skill to set up safety rails in a new or existing repository, or globally for the agent.

0 0
Explore
stars-end/agent-skills

beads-guard

Safe Beads workflow helper (warning-only). Use before bd sync/close/create to avoid JSONL conflicts. Ensures you are on a feature branch, up to date with origin/master, and stages Beads files cleanly with Feature-Key commits.

0 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results