AgentSkillsCN

package-json-develop

组织并维护 package.json 的 scripts 部分，以提升可读性和可维护性。当您：(1) 重新组织庞大的 package.json scripts 部分；(2) 添加注释分隔符以分组脚本；(3) 将复杂的多进程命令提取为 Shell 脚本；(4) 设置多环境开发命令（本地/预览/生产）；(5) 用户提及“组织 package.json”、“package.json 可读性”、“scripts 部分”或“多进程开发脚本”时，可使用此技能。关键词：package.json、npm scripts、组织、分隔符、Shell 脚本、多进程、开发环境。

SKILL.md
--- frontmatter
name: package-json-develop
description: >
  Organize and maintain package.json scripts sections for readability and maintainability. Use when:
  (1) Reorganizing a large package.json scripts section, (2) Adding comment separators to group
  scripts, (3) Extracting complex multi-process commands into shell scripts, (4) Setting up
  multi-environment dev commands (local/preview/production), (5) User mentions 'organize
  package.json', 'package.json readability', 'script sections', or 'multi-process dev script'.
  Keywords: package.json, npm scripts, organize, separator, shell script, multi-process, dev
  environment.

package.json Scripts Organization

Two techniques for keeping large scripts sections readable and maintainable.

Technique 1: Comment Separator Keys

Add visual section dividers using unused JSON keys:

json
{
  "scripts": {
    "// ── Core ─────────────────────────────────────────": "",
    "dev": "next dev",
    "build": "next build",
    "// ── Testing ─────────────────────────────────────": "",
    "test": "jest",
    "test:e2e": "playwright test"
  }
}

Format: "// ── Section Name ──────..." with ─ padding to ~50 chars, value "".

Technique 2: External Shell Scripts for Multi-Process Commands

When a command starts 2+ background processes, extract to scripts/*.sh.

Template available at scripts/multi-process-dev.sh.template. Key pattern:

bash
#!/bin/bash
set -e
cleanup() {
  kill $PID_1 $PID_2 2>/dev/null
  wait $PID_1 $PID_2 2>/dev/null
}
trap cleanup EXIT INT TERM

if [ "$MODE" = "local" ]; then
  backend-server &
  PID_1=$!
  sleep 3
fi

pnpm dev &
PID_2=$!
wait

Call from package.json: "dev:full": "MODE=local ./scripts/dev-full.sh"

Make executable: chmod +x scripts/*.sh

Multi-Environment Pattern

For apps with local/preview/production API targets:

json
{
  "// ── Dev with API (3 environments) ───────────────": "",
  "dev:full": "API_MODE=local ./scripts/dev-full.sh",
  "dev:full:preview": "API_MODE=preview pnpm dev",
  "dev:full:prod": "API_MODE=production pnpm dev"
}

Detailed Patterns

See references/patterns.md for:

  • •Full list of suggested section names
  • •Namespace prefixing for monorepo sub-packages
  • •Internal/private script conventions (_ prefix)
  • •Complete multi-process shell script template with explanations