Skip to main content
skill CX Codex

pl-env — Claude Code skill: environment checks and install

The pl-env Claude Code skill checks a project environment and investigates blockers before test runs or VM work. The core pl skill loads it through its routing table.

Apache-2.0 ★ 869 updated 2026-11-16

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add sno-ai/sno-station-skills --skill pl-env -a claude-code
Open on GitHub

What pl-env does

The skill checks services, resources, dependencies, workspace state, and credentials. The core pl loads it when the environment is in doubt, a restart is requested, a VM is involved, or an evaluation or end-to-end run is about to begin. It is not meant to be invoked directly.

Checks use general-env-doctor.sh and docker-env-doctor.sh. The first inspects environment state, looks up named secrets, and queries the host registry; the second checks whether a Docker service can be restarted. Shell access and file read/write are required. The optional host registry, secrets wrapper, and model endpoint use SNO_ROSTER_FILE, SNO_SECRETS_CMD, and OPENAI_BASE_URL. Without a registry, the VM check reports that none is configured and does not establish VM availability.

Before a Docker restart, the script checks whether the action is justified and blocks it if another session has work in progress. Direct process termination with pkill or kill -9 is forbidden by default. Docker verdicts are appended to ai-doc/ACTIVE/PL/docker-env-doctor-verdicts.jsonl.

What it helps with

  • check whether a service or host is reachable
  • look up a credential in the shell and configured source
  • probe a VM before dispatching a run
  • check whether a Docker service restart is allowed

Example prompts for the agent

  • Core pl, investigate why the service is unavailable and check the environment.
  • Core pl, check whether the VM is reachable before starting the run.
  • Core pl, determine whether this Docker service can be restarted.

How to install pl-env

1Skills CLI (Vercel)

npx skills add sno-ai/sno-station-skills --skill pl-env -a claude-code

2Manually: put the files in place

~/.claude/skills/pl-env/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/pl-env/

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

Questions about pl-env

How do I install pl-env in Claude Code?

Run npx skills add sno-ai/sno-station-skills --skill pl-env -a claude-code. The skill file is installed at ~/.claude/skills/pl-env/SKILL.md.

What does pl-env do?

It checks environment state, credentials, hosts, and Docker services. The core pl loads it through its routing table; it is not invoked directly.

What does pl-env need to work?

Shell access and file read/write are required. The host registry, secrets wrapper, and model endpoint are optional settings configured through SNO_ROSTER_FILE, SNO_SECRETS_CMD, and OPENAI_BASE_URL.

Source text

SKILL.md · Apache-2.0
---
name: pl-env
description: "PL role sub-skill — environment doctoring. Loaded ONLY by the pl core via its routing table; NEVER auto-load from context, never invoke directly."
requires:
  programs: []
  harness:
    - {slot: 4.shell, need: required}
    - {slot: 4.file-read-write, need: required}
---

# PL · Env — environment self-service

Scripts named below run as `bash "${PL_SKILL_DIR}/scripts/<name>.sh" ...`, where `PL_SKILL_DIR` is the
absolute path of the `pl` skill directory; set it in the same Bash call.

Sub-skill of the PL role. The pl core skill invokes this EXPLICITLY on any
environment doubt: a "not available / missing / down" claim, a restart wish, a
VM/host question, or before opening an evaluation or end-to-end run. Canonical scripts:
the pl skill's `scripts/`. Read the host/VM registry from `${SNO_ROSTER_FILE:-}`;
when unset, report "no roster configured" and continue. The TSV columns are
name, address, kind, purpose, and check; no machine inventory ships with the skill.
Use the repo's documented service-address source when one exists.
Read `${SNO_SECRETS_CMD:-}` for an optional secrets wrapper: one executable path
that accepts a command and its arguments, injects secrets, and preserves its exit status.
When unset, report "no secrets wrapper configured" and continue.
Read `${OPENAI_BASE_URL:-}` for model connectivity; when unset, report
"using the harness's own endpoint" and continue.
**Known environment traps**: read the project's lessons file (`ai-doc/LESSONS.md`) when it exists;
propose additions by card.

## Environment self-service

The environment doctor is software-flavoured: each check below applies when the project uses that
tool (Docker, uv/bun, git, a GPU, a VM roster); a check for a tool the project does not use is
reported as not applicable, never as a failure.

Environment, resource, and startup blockers are yours (and every executor's) to
fix, not to wait on — parking on an environment blocker without attempted
self-service is a protocol violation. Most external stalls are environment-class,
and a large share of those are FALSE blockages built on stale premises. Hence:

1. **Fresh evidence or it didn't happen**: any BLOCKED-on-environment verdict
   must attach the on-the-spot command + output (health probe, `docker ps`,
   `ls`, configured secrets-wrapper check). A remembered/recorded "not available" is invalid.
2. **Self-serve the fix — `general-env-doctor.sh` is the standard tool**:
   run `bash "${PL_SKILL_DIR}/scripts/general-env-doctor.sh"` (optionally `--fix`) before ever declaring an environment blocker.
   Classes: secrets / creds (auto-repair through the configured wrapper) /
   connectivity / deps (uv/bun sync, CLI tools) / workspace (stale locks,
   scratch directory, disk) / drift (documented ports versus Docker listeners).
   `bash "${PL_SKILL_DIR}/scripts/general-env-doctor.sh" secret <NAME>` answers "the key is missing" claims —
   it checks this shell and the configured secrets wrapper
   without printing values; every name, including API-key names, takes the same lookup.
   An unset wrapper is an unavailable check, not a missing key.
   Query the supplied roster with `bash "${PL_SKILL_DIR}/scripts/general-env-doctor.sh" host [<name>]`.
   Before dispatching a VM-dependent journey, run `bash "${PL_SKILL_DIR}/scripts/general-env-doctor.sh" vm`.
   A missing roster reports "no roster configured" and proves no VM reachable;
   obtain the run's host configuration before dispatching. A failed VM probe
   means do not dispatch onto it.
3. **Restart of a RUNNING service is script-gated** (when the project uses Docker): run
   `bash "${PL_SKILL_DIR}/scripts/docker-env-doctor.sh" <service>` (deterministic).
   `START`/`RESTART_OK` → run `bash "${PL_SKILL_DIR}/scripts/docker-env-doctor.sh" <service> --execute`
   (Docker Compose by default, or the executable named by `ENV_DOCTOR_REBUILD_CMD`; two more optional settings, `ENV_DOCTOR_COUNTER_REQUIRED_RE` (services that must pass a work-counter probe) and `ENV_DOCTOR_QUEUES` (Redis queues that must be empty), are described in the script header); `NO_GROUNDS` → investigate logs instead;
   `BLOCKED_BUSY` → another session's work is in flight: do not restart,
   report with the script's evidence; `INDETERMINATE` → a safety signal could not be verified: take no
   action and report which signal is missing. By default, direct process kills (`pkill`,
   `kill -9`) are forbidden. Verdicts auto-append to
   `ai-doc/ACTIVE/PL/docker-env-doctor-verdicts.jsonl` (audit trail).
4. **Escalate only five things** ("the owner" means whoever owns the work, often the user): restart denied by the busy check; shared
   prod-data mutations; money; interactive auth (gcloud/gh login — state the
   exact command the owner must run); a resource verified absent that needs
   provisioning. Escalations are precise, never a generic "environment stuck".
   Money beyond the ceiling or an existing grant, and any irreversible action that leaves the
   machine, go straight to the owner: the PL sends that card to `SNO_OWNER_ADDR` (the owner's own
   Reach address, exported before the PL starts) with the COS that supervises this lane (the
   Chief of Staff agent; see the pl core's Terms) on Cc, and that COS may not approve, hold or
   edit it (bands and lists: the live decision-rights file,
   `~/.config/sno/decision-rights.md` when present, otherwise the shipped `references/decision-rights.md` in the pl skill).
   **A credential is never one of the five.** "I cannot find the key" and "I am
   locked out" are not escalations at any layer; check the available credential
   sources first. Interactive auth stays legal only
   because a browser genuinely needs a human at it, and only with the exact
   command written out; it is not a place to file a key you did not find.

## Keys — the one class that is never an escalation

Two rules outrank everything else in this file: **never lock yourself out, never
lose the key**. The encrypted-store rule below applies when the project stores encrypted
user data. The operational half is here because this is where an agent lands the moment a
key fails.

- **`bash "${PL_SKILL_DIR}/scripts/general-env-doctor.sh" secret <NAME>`** — the `secret` lookup in item 2. Run it
  before the thought "the key is missing" is allowed to become a sentence in a
  card. If the configured sources miss, inspect the repository's documented
  credential source before declaring the key absent.
- **A failure to open an encrypted store is a defect, not a finding.** Never write it into a
  document as a known limitation, never trade it away, never weaken encryption on
  user data to get past it. Build the rescue road, and prove it by really making
  the keyring unusable and really opening an encrypted store — a simulated
  failure proves nothing, and a restore procedure nobody has run does not exist.

## Pre-run environment self-check

Before opening any evaluation or end-to-end run, check the host you will run it on ONCE: probe
the run's real dependencies up front and declare any degradation BEFORE the run starts. A
failing probe means choose the host NOW from the available ones; do not discover the
degradation mid-run, where it costs rounds on a degraded attempt before the host question is
even asked.

© sno-ai · Apache-2.0 · sno-ai/sno-station-skills

Similar skills

SKILL.md skills catalog →

From the same set40

The whole set →
pl This Claude Code skill supervises one project lane and its executor agents. It activates when the owner types /pl, uses $pl, or assigns the Project Lead role. CX Codex +1 ★ 869repo stars pl-watch The pl-watch Claude Code skill gives a Project Lead rules for supervising active executors. The PL core loads it for incoming cards, stalls, watch events, and other work in progress. CX Codex +1 ★ 869repo stars pl-dispatch The pl-dispatch Claude Code skill helps a Project Lead open a work journey and prepare its dispatch. The pl core routing table loads it for scheduling decisions or requests to start work. CX Codex +1 ★ 869repo stars pl-audit The pl-audit Claude Code skill checks executor reports and task closure. The pl core skill routes it in when a report or a closure signal arrives. CX Codex +1 ★ 869repo stars pl-analyze The pl-analyze skill for Claude Code investigates incidents and reviews process failures. It activates through PL routing or an explicit request for a retrospective or root-cause report. CX Codex +1 ★ 869repo stars cos A Claude Code skill, cos coordinates the project owner and project leads. It activates on /cos, $cos, or a direct request to act as Chief of Staff. CX Codex +1 ★ 869repo stars cos-watch The cos-watch Claude Code skill monitors active PLs, checking liveness, wake cycles, and task order. The COS core loads it through its routing table while work is in flight. CX Codex +1 ★ 869repo stars cos-review The cos-review Claude Code skill audits decisions, completed work, and estimates after a declared night shift. COS core routes it in when the owner returns or a batch of closes lands. CX Codex +1 ★ 869repo stars

Project sponsors

Companies that keep this analytics open