agentleFS
lingengyuanlingengyuan/my-skills/.claude/skills/portpilot-assistant/SKILL.md

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.

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
  1. Very specific:

    Allocate ports (pick): When starting a service, request a lease.

    line 37
  2. Very specific:

    Always execute who <port> to inspect the process name, PID, working directory, and start time.

    line 39
  3. Very specific:

    If the process is a recognized development server created for the task, proceed with free.

    line 40
  4. Distinctive:

    If the process is unexpected, shared, or a system daemon, ask for user confirmation before terminating.

    line 41
  5. Very specific:

    Inspect first: Never terminate a process with free without first identifying its PID and command line.

    line 46
  6. Distinctive:

    Permission elevation: Use normal user permissions first.

    line 47
  7. Distinctive:

    Signal escalation: Prefer standard termination signals before forced termination.

    line 48
  8. Distinctive:

    Before completing the task, verify:

    line 54

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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" --help

In POSIX environments, scripts/run_portpilot.sh provides an optional wrapper for the same binary.

Commands Reference

CommandDescriptionExample
pickReserve an available port with temporary leasenode "<cli>" pick --range 3000-3999 --count 1 --lease-ms 20000 --json
claimConsume an existing port leasenode "<cli>" claim --lease-id <id> --json
scanList currently listening ports and servicesnode "<cli>" scan --protocol both --json
whoIdentify process owning a specific portnode "<cli>" who 3000 --json
doctorDiagnose configuration issues and port conflictsnode "<cli>" doctor --json
freeTerminate process holding a target portnode "<cli>" free 3000 --yes --json
initCreate default port configurationnode "<cli>" init --dry-run --json
configView or migrate PortPilot configurationnode "<cli>" config migrate --json

Workflow

  1. Map user intent: Identify the matching subcommand using references/intent-map.md.
  2. Execute read-only commands: Pass --json to produce machine-readable output. Parse the JSON result directly.
  3. Allocate ports (pick): When starting a service, request a lease. State the allocated port and lease expiration in the response.
  4. 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.
  5. 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 free without 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:

  1. Target port status matches who or scan output.
  2. Allocated lease IDs and expiry times are recorded when using pick.
  3. Target port is unbound after executing free.
  4. Output report states the final port state clearly.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.