cleanup-package-json

Original：🇨🇳 Chinese
Translated

Organize and clean up scripts and dependencies in package.json. Use this for requests such as 'I want to clean up package.json', 'I want to organize scripts', or 'I want to remove unused dependencies'. Specifically, it targets the following: (1) Delete or integrate redundant scripts (aliases/passthroughs), (2) Explicitize implicit lifecycle hooks (pre/post), (3) Unify script naming conventions, (4) Detect and remove unused dependency packages, (5) Update documents and CI following script name changes, (6) Regenerate lock files after removing dependencies.

1installs
Sourcenimiusrd/agent-skills
Added on

NPX Install

npx skill4agent add nimiusrd/agent-skills cleanup-package-json

Tags

Translated version includes tags in frontmatter
package-json-cleanupscript-organizationdependency-managementci-document-updatelockfile-regeneration

SKILL.md Content (Chinese)

View Translation Comparison →

cleanup-package-json

Workflow

1. Current Status Assessment

Read the 
package.json
and identify issues from the following perspectives:
Script Checkpoints:
  • Aliases: Scripts that only call another script (e.g., 
    "build": "npm run build:app"
    )
  • Passthroughs: Scripts that just pass through commands directly (e.g., 
    "lint": "eslint"
    )
  • Implicit Lifecycle Hooks: 
    preX
    /
    postX
    hooks (e.g., 
    "prebuild": "npm run codegen"
    )
  • Inconsistent Naming: Related scripts are not grouped (e.g., 
    e2e
    is not included in the 
    test:*
    series)
Dependency Checkpoints:
  • Search each package in 
    dependencies
    /
    devDependencies
    via import statements in the source code to identify unused ones
  • Determine the target search directories based on the project structure (e.g., 
    src/
    , 
    lib/
    , 
    app/
    )

2. Present Issues and Confirm

Present the identified issues to the user and confirm which ones to fix. Provide options and obtain consensus before proceeding with the work.

3. Script Modifications

Edit the 
package.json
once confirmation is obtained.
Typical Conversion Patterns:
PatternBefore ConversionAfter Conversion
Alias Integration
"build": "npm run build:app"
+ 
"build:app": "A && B"
"build": "A && B"
Pre-hook Explicitization
"prebuild": "npm run X"
+ 
"build": "Y"
"build": "npm run X && Y"
Passthrough Removal
"lint": "eslint"
Remove (either call 
eslint
directly or eliminate if unnecessary)
Naming Unification
"e2e": "playwright test"
"test:e2e": "playwright test"
Determine which package manager (
npm run
/
yarn
/
pnpm run
) is being used from the 
package.json
or the presence of lockfiles, and use the appropriate one.

4. Confirm Document Updates

If script names are changed or deleted, check if those names appear in the following files and modify them if necessary:
  • README.md
  • Agent-facing documents such as 
    CLAUDE.md
    / 
    AGENTS.md
  • Workflow files under 
    .github/workflows/
  • Documents under 
    docs/

5. Regenerate Lock Files After Dependency Removal

If dependency packages are removed, delete 
node_modules
and the lockfile, then run install.
bash
# npm
rm -rf node_modules package-lock.json && npm install

# yarn
rm -rf node_modules yarn.lock && yarn install

# pnpm
rm -rf node_modules pnpm-lock.yaml && pnpm install

Notes

  • Removing Pre-hooks: If you remove 
    preX
    hooks and call them explicitly, the (unintended) hooks will no longer run even when the script is called alone. Since this changes the behavior, confirm with the user before converting.
  • Changing Script Names: If you change script names that are referenced in CI or documents, be sure to update the references accordingly.
  • Native Integration Packages: npm packages that bridge with native layers such as Tauri/Electron may actually be necessary even if there are no imports on the JS side. Check runtime requirements before deleting.
  • Indirect Dependencies: Even if listed in 
    dependencies
    , some packages may not be imported directly (e.g., Babel plugins, ESLint presets referenced via configuration files). Confirm via build/test before deleting.