portpilot-assistant
Skill9 starsChanged 3 days agoMITView on GitHub
Inspect, diagnose, allocate, and free local development ports using the bundled PortPilot CLI. Use when finding available ports, inspecting port listeners, resolving port conflicts, freeing ports, or managing PortPilot configuration.
In this repository17 other files it gives its agents.
- brief-outputSkill
- google-go-styleSkill
- insight-collectorSkill
- insights-reportSkill
- json-canvasSkill
- md2wechatSkill
- note-creatorSkill
- obsidian-basesSkill
- obsidian-markdownSkill
- peleSkill
- publication-ready-docs-jevSkill
- publication-ready-docsSkill
- readme-maintainerSkill
- sync-to-githubSkill
- tech-articleSkill
- wechat2mdSkill
- wechat-archiverSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 4 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 37
Allocate ports (
pick): When starting a service, request a lease. - Very specific: line 39
Always execute who <port> to inspect the process name, PID, working directory, and start time.
- Very specific: line 40
If the process is a recognized development server created for the task, proceed with free.
- Distinctive: line 41
If the process is unexpected, shared, or a system daemon, ask for user confirmation before terminating.
- Very specific: line 46
Inspect first: Never terminate a process with free without first identifying its PID and command line.
- Distinctive: line 47
Permission elevation: Use normal user permissions first.
- Distinctive: line 48
Signal escalation: Prefer standard termination signals before forced termination.
- Distinctive: line 54
Before completing the task, verify:
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
PortPilot Assistant Skill
Inspect, allocate, and manage local network development ports using the bundled PortPilot CLI. Node.js 18+ is required. No global npm installation is needed.
CLI Location
Resolve the bundled executable relative to this Skill's directory:
node "<skill-dir>/assets/portpilot/bin/portpilot.js" --helpIn POSIX environments, scripts/run_portpilot.sh provides an optional wrapper for the same binary.
Commands Reference
| Command | Description | Example |
pick | Reserve an available port with temporary lease | node "<cli>" pick --range 3000-3999 --count 1 --lease-ms 20000 --json |
claim | Consume an existing port lease | node "<cli>" claim --lease-id <id> --json |
scan | List currently listening ports and services | node "<cli>" scan --protocol both --json |
who | Identify process owning a specific port | node "<cli>" who 3000 --json |
doctor | Diagnose configuration issues and port conflicts | node "<cli>" doctor --json |
free | Terminate process holding a target port | node "<cli>" free 3000 --yes --json |
init | Create default port configuration | node "<cli>" init --dry-run --json |
config | View or migrate PortPilot configuration | node "<cli>" config migrate --json |
Workflow
- Map user intent: Identify the matching subcommand using references/intent-map.md.
- Execute read-only commands: Pass
--jsonto produce machine-readable output. Parse the JSON result directly. - Allocate ports (
pick): When starting a service, request a lease. State the allocated port and lease expiration in the response. - Inspect before terminating (
free):- Always execute
who <port>to inspect the process name, PID, working directory, and start time. - If the process is a recognized development server created for the task, proceed with
free. - If the process is unexpected, shared, or a system daemon, ask for user confirmation before terminating.
- Always execute
- Report findings: State the direct answer first (e.g., port availability, PID owner, conflict cause), followed by command details.
Safety Rules
- Inspect first: Never terminate a process with
freewithout first identifying its PID and command line. - Permission elevation: Use normal user permissions first. Request elevation (sudo/administrator) only when permission restrictions occur on an authorized task.
- Signal escalation: Prefer standard termination signals before forced termination. Never kill unrelated system services.
See references/safety-policy.md for detailed process management policies.
Verification Checklist
Before completing the task, verify:
- Target port status matches
whoorscanoutput. - Allocated lease IDs and expiry times are recorded when using
pick. - Target port is unbound after executing
free. - Output report states the final port state clearly.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

