ln-005-environment-scanner
Probes CLI agents (Codex, Gemini) and writes environment_state.json. Use when setting up a project or after installing/removing CLI agents.
How do I install this agent skill?
npx skills add https://github.com/levnikolaevich/claude-code-skills --skill ln-005-environment-scannerIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The environment scanner skill identifies installed CLI agents by executing local health-check scripts and version commands. It maintains a state file in the documentation directory. The skill operates entirely within the local file system and repository structure, with no network activity or sensitive data access detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerpass
1/2 files flagged
What does this agent skill do?
Paths: File paths (
shared/,references/,../ln-*) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root.
Environment Scanner (Standalone Utility)
Type: Standalone Utility Category: 0XX Shared
Probes CLI agents (Codex, Gemini) and writes docs/environment_state.json. Skills read this file to check disabled flags before live-probing agents.
When to Use This Skill
- First-time project setup (no
docs/environment_state.jsonyet) - After installing/removing CLI agents (Codex, Gemini)
- After
ln-004-agent-config-sync(sync may change agent availability) - When a skill reports unexpected agent unavailability
Output File
docs/environment_state.json — validated against references/environment_state_schema.json.
{
"$schema": "environment_state_v1",
"scanned_at": "2026-03-08T14:30:00Z",
"agents": {
"codex": { "available": true, "version": "0.1.2503" },
"gemini": { "available": false, "detail": "Command not found in PATH" }
}
}
User Override
Users can add "disabled": true to any agent entry to opt out without losing detection state:
"codex": { "available": true, "disabled": true, "version": "0.1.2503" }
Scanner preserves disabled field on rescan — it overwrites available, detail, version but never touches disabled.
How skills use this: Before running --health-check, skills read this file. If disabled: true → agent is skipped immediately (no probe). If disabled: false or absent → live health-check runs.
Workflow
Probe Agents → Write JSON → Summary
Phase 1: Probe CLI Agents
Single call to agent_runner.mjs --health-check probes all registered agents:
node shared/agents/agent_runner.mjs --health-check
Path resolution: shared/agents/agent_runner.mjs is relative to skills repo root. Locate via this SKILL.md directory → parent.
Parse output (JSON with per-agent status):
| Agent | Registry Key | State Fields |
|---|---|---|
| Codex | codex (checks codex --version) | available, version (first line of version output) |
| Gemini | gemini (checks gemini --version) | available, version (first line of version output) |
If agent_runner.mjs not found or errors: Set both agents to available: false, detail: "agent_runner.mjs not available".
Phase 1.5: Hook Health Check
MANDATORY READ: Load shared/references/hook_health_check.md
Validate hooks configuration: JSON syntax, script existence, dependency availability. Append results to docs/environment_state.json under hooks key:
"hooks": {
"status": "ok",
"events": 3,
"scripts_found": "3/3",
"dependencies": { "node": "22.0.0" }
}
If hooks.json not found: "hooks": { "status": "not_configured" }.
Phase 2: Write JSON
- Read existing state (if
docs/environment_state.jsonexists):- Preserve
disabledfields from existing entries - Preserve any user-added custom fields
- Preserve
- Build new state:
$schema:"environment_state_v1"scanned_at: current ISO 8601 timestampagents: merge probe results (newavailable/detail/version) with preserveddisabledflags
- Ensure
docs/directory exists (create if missing) - Write
docs/environment_state.jsonwith 2-space indentation - Validate written file against
references/environment_state_schema.jsonstructure (key presence check)
Phase 3: Summary Report
Display results as a table:
Environment Scan Complete:
| Agent | Status | Detail |
|--------|-------------|---------------------------|
| Codex | available | 0.1.2503 |
| Gemini | unavailable | Command not found in PATH |
State written to: docs/environment_state.json
If any agent has disabled: true, show status as disabled (not available/unavailable).
Critical Rules
- Probe all agents. This skill always probes ALL agents, regardless of existing state. It is the full rescan.
- Preserve
disabled. Never overwrite user'sdisabled: trueflags. Detection state updates, user preference stays. - No side effects. This skill only writes
docs/environment_state.json. No other files modified. - Fail gracefully. Each probe is independent. One failure = one
available: falseentry, scan continues. - No TTL. State file has no expiration. It is refreshed only by running this skill.
Anti-Patterns
| DON'T | DO |
|---|---|
| Skip probes for "known" agents | Always probe all agents — this is a full scan |
Delete disabled flags on rescan | Merge: overwrite detection fields, preserve disabled |
| Retry failed probes | One attempt per agent. Failure = available: false |
| Probe MCP tools or platform | Only probe CLI agents (Codex, Gemini). MCP tools configured elsewhere |
| Add TTL or cache expiry logic | State is manual-refresh only |
Definition of Done
- Both agents probed (Codex, Gemini)
- Hook health check completed (hooks.json, scripts, dependencies)
-
docs/environment_state.jsonwritten with valid structure (agents + hooks) - Existing
disabledflags preserved across rescan - Summary table displayed to user
Version: 2.0.0 Last Updated: 2026-03-08
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/levnikolaevich/claude-code-skills/ln-005-environment-scanner">View ln-005-environment-scanner on skillZs</a>