Skip to main content Skills Marketplace Discover and explore AI skills built by the community.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Show prompt details A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/guo-yu/skills --skill port-allocatorThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Download Zip Downloading... More from this repository
Related occupations SOC
Based on SOC occupation classification
name port-allocator description Automatically allocate and manage development server ports, avoiding port conflicts between multiple Claude Code instances
Port Allocator
Smart port allocator that only assigns ports to real projects containing package.json.
Usage
Command Description /port-allocatorAllocate/query port for current project /port-allocator listList all allocated ports /port-allocator scanScan code directory, discover and allocate ports for new projects /port-allocator config <path>Set the main code directory path /port-allocator add <dir-path>Manually add port allocation for a project /port-allocator allowConfigure Claude Code permissions for this skill's commands
Important Rules
1. Only Operate on Current Project's Ports When Restarting Services
When restarting the development server, only kill processes within the current project's port range , never affect other ports:
lsof -ti:3000 | xargs kill -9 2>/dev/null
lsof -ti:3001 | xargs kill -9 2>/dev/null
pkill -f node
lsof -ti:3010 | xargs kill
2. Append Rather Than Overwrite When Updating CLAUDE.md When updating ~/.claude/CLAUDE.md, must preserve the user's existing content :
Execution Steps
Command: /port-allocator allow Configure Claude Code to allow commands used by this skill, avoiding manual confirmation each time:
Read ~/.claude/settings.json (if exists)
Merge the following commands into permissions.allow array (preserve existing config):
{
"permissions" : {
"allow" : [
"Bash(ls -d *)" ,
"Bash(find * -maxdepth * -name package.json *)" ,
"Bash(cat ~/.claude/*)" ,
"Bash(dirname *)" ,
"Bash(lsof -i:3*)" ,
"Bash(lsof -ti:3*)"
]
}
}
Write updated settings.json
Output the list of added permissions
Configured Claude Code permissions
Added allowed command patterns:
- Bash(ls -d *)
- Bash(find * -maxdepth * -name package.json *)
- Bash(cat ~/.claude/*)
- Bash(lsof -i:3*)
- Bash(lsof -ti:3*)
Config file: ~/.claude/settings.json
Command: /port-allocator config <path> Set the user's main code directory:
Verify path exists (required! Error and exit if not found)Update code_root field in ~/.claude/port-registry.json
Output confirmation
First Run: Auto-Detection On first run (when ~/.claude/port-registry.json doesn't exist or has no code_root), automatically detect the code directory:
for dir in ~/Codes ~/Code ~/Projects ~/Dev ~/Development ~/repos; do
if [ -d "$dir " ]; then
CODE_ROOT="$dir "
break
fi
done
CODE_ROOT="${CODE_ROOT:-~/Codes} "
First run, detecting code directory...
Code directory detected: ~/Codes
Port registry initialized: ~/.claude/port-registry.json
To change, use:
/port-allocator config ~/your/code/path
Could not auto-detect code directory.
Please configure manually:
/port-allocator config ~/your/code/path
Common locations:
~/Codes, ~/Code, ~/Projects, ~/Dev
Command: /port-allocator scan Scan code directory, automatically discover and register projects:
Read ~/.claude/port-registry.json to get code_root
If config doesn't exist, run auto-detection first
If code_root directory doesn't exist, prompt user to configure
Find all directories containing package.json (exact to package.json location):
find <code_root> -maxdepth 3 -name "package.json" -type f \
-not -path "*/.next/*" \
-not -path "*/node_modules/*" \
-not -path "*/dist/*" \
-not -path "*/build/*" | while read pkg; do
dirname "$pkg "
done
Important : Path must be exact to the directory containing package.json
Correct: ~/Codes/chekusu/landing
Wrong: ~/Codes/chekusu (if package.json is in subdirectory)
For each discovered project directory:
Check if already in registry
If not, allocate next available port range
Update config file (append mode , don't overwrite user content)
Output scan result summary
Command: /port-allocator (default) Allocate/query port for current project:
Get current working directory
Read config to get code_root and allocated ports
Match current directory to corresponding project
If no package.json, indicate this is not a project needing ports
If exists, check if port already allocated, auto-allocate if not
Output port info
Command: /port-allocator list List all allocated ports (read-only operation).
Output Format
Port Information Project directory: ~/Codes/chekusu/landing
package.json: Detected
Port range: 3000-3009
- Main app: 3000
- API: 3001
- Other services: 3002-3009
Warning: Only operate on ports 3000-3009 when restarting services!
Scan Results Scan complete: ~/Codes
Registered projects (N):
- chekusu/landing: 3000-3009
- saifuri: 3010-3019
Newly discovered projects (M):
- new-project: 3090-3099 (newly allocated)
Skipped (K):
- .next, node_modules (build artifacts)
- research-folder (no package.json)
Port Allocation Rules
Each project is allocated 10 consecutive ports
Starting port: 3000
Interval: 10
x0: Main application (e.g., 3000, 3010, 3020)x1: API service (e.g., 3001, 3011, 3021)x2-x9: Other services (database, cache, etc.)
Configuration Files
Port registry : ~/.claude/port-registry.jsonGlobal instructions : ~/.claude/CLAUDE.md (append mode updates)Claude Code settings : ~/.claude/settings.json (stores allowedCommands)Skip patterns : .next, node_modules, dist, build
Notes
Only operate on project ports - Never affect other projects when restarting servicesAppend not overwrite - Preserve user's existing content when updating config filesPrecise paths - Point to actual directory containing package.jsonSkip build artifacts - .next, node_modules, etc. don't get port allocationFirst use - Recommend running /port-allocator allow to configure permissions first 