# Lingengyuan My Skills Portpilot Assistant

> PortPilot Assistant

- Skill: `tomevault-io/lingengyuan-my-skills-portpilot-assistant` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/lingengyuan-my-skills-portpilot-assistant`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/lingengyuan-my-skills-portpilot-assistant/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/lingengyuan-my-skills-portpilot-assistant

---


# PortPilot Assistant

Translate natural language into `portpilot` commands with safe defaults.

## Workflow

1. Classify intent into one of: `scan`, `who`, `pick`, `doctor`, `free`, `init`, `config`.
2. Resolve target port/range/path from user text; if absent, apply defaults.
3. For the first `portpilot` call in a new session, run one permission bootstrap to avoid repeated prompts (details below).
4. Execute read actions directly (`scan`, `who`, `pick`, `doctor`).
5. For write actions (`free`, `init --force`, `config migrate`), require explicit confirmation and show details.
6. Return concise conclusion first, then command output details.

## Intent mapping

- 帮我选个端口 / pick a port:
  - `portpilot pick --range 3000-3999 --count 1 --lease-ms 20000 --json`
- 扫描当前端口 / scan current used ports:
  - `portpilot scan --protocol both --json`
- 查看 3000 端口 / check port 3000:
  - `portpilot who 3000 --json`
- 释放 3000 端口 / free port 3000:
  - First `portpilot who 3000 --json`, then confirm, then `portpilot free 3000 --yes --json`
- 扫描冲突 / run doctor:
  - `portpilot doctor --json`
- 初始化配置 / init port config:
  - `portpilot init --dry-run --json` (default preview)

## Safety policy

- Read actions run automatically.
- Write actions require confirmation.
- Confirmation payload must include: `port`, `pid`, `command`, `cwd`, `startTime`, `action`.
- If dependency failure occurs, run `portpilot doctor --preflight --json` and return install/fix commands.

## Permission bootstrap (one-time)

- On the first `portpilot` action in a new session, proactively run one lightweight bootstrap command (`portpilot doctor --json`) with escalation.
- Resolve bundled CLI absolute path first (path-independent):
  - Preferred: `$CODEX_HOME/skills/portpilot-assistant/assets/portpilot/bin/portpilot.js`
  - Fallback for repo-local usage: `<repo>/.claude/skills/portpilot-assistant/assets/portpilot/bin/portpilot.js`
- In that one-time escalation request, set:
  - `sandbox_permissions: require_escalated`
  - `prefix_rule: ["node", "<resolved-portpilot-cli-absolute-path>"]`
- Explain that this is a one-time approval to avoid repeated prompts for future `portpilot` commands.
- After approval, run requested commands normally without escalation.
- If bootstrap was not done (or approval was denied), and a read action fails with permission errors (`Operation not permitted` / netlink denied / `lsof` denied), rerun once with escalation.
- Write actions still require explicit user confirmation before execution.

## Execution notes

- Run bundled CLI from this skill first: `assets/portpilot/bin/portpilot.js`.
- Fallback to npx only if bundled CLI is missing: `npx -y portpilot-cli@1 ...`.
- Always pass `--json` for machine-readable parsing in skill scripts.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/lingengyuan) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-12 -->