agentleFS
ats4321ats4321/claude-engineering-skills/skills/dependency-management/SKILL.md

Dependency Management

Skill0 starsChanged 4 months agoMITView on GitHub

Dependency discipline for any ecosystem (pip/pyproject, npm/pnpm, cargo, etc.). Load when adding, upgrading, pinning, or removing a dependency; when reading lock files or version constraints; when diagnosing transitive-dependency breakage ("worked yesterday, broken today", import errors after fresh install); when deciding narrow pin vs floating range; or when auditing whether a new dependency is needed at all. Covers constraint syntax, pin-vs-float decision rules, documenting WHY pins exist, and stdlib-first auditing.

  • Deletes or force-pushes
  • Installs packages

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 6 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Run this decision tree BEFORE any pip install / npm install of a new package.

    line 32
  2. Distinctive:

    If there is no lock file (common in small Python projects), the manifest constraints ARE the reproducibility mechanism — they must carry …

    line 55
  3. Distinctive:

    Put the reason in the commit message ("Pin numpy for chromadb 0.4"), a manifest comment, or the README.

    line 70
  4. Distinctive:

    When installs break without a code change:

    line 75
  5. Distinctive:

    Read the full traceback — the failing import names the guilty package, which is often NOT one you declared.

    line 78
  6. Very specific:

    Check whether the intermediate package declares an upper bound on the culprit.

    line 80
  7. Distinctive:

    Every version ceiling/pin in the manifest has a discoverable WHY and lift condition.

    line 161
  8. Distinctive:

    When diagnosing breakage, you named the exact transitive package AND the intermediate dep that pulls it in, before editing anything.

    line 163

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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

Dependency Management

Purpose

Manage third-party dependencies deliberately: audit before adding, constrain with intent, and diagnose breakage caused by packages you never named. The core doctrine is minimal dependencies — every dependency is code you now maintain without owning — and every version pin must have a written reason.

When to Use / When NOT to Use

Use when:

  • Adding any new dependency to a project (ALWAYS run the audit in Step 1 first).
  • Choosing or changing a version constraint (>=, <, ^, ~, exact pin).
  • A fresh install breaks but the code did not change (classic transitive-dep signature).
  • Reading or updating lock files (package-lock.json, pnpm-lock.yaml, poetry.lock, Cargo.lock) or constraint files (pyproject.toml, package.json, Cargo.toml).
  • Reviewing a diff that touches dependency manifests.

Do NOT use when:

  • The failure is in your own code logic → load debugging-playbook.
  • The question is which config value controls behavior → load configuration-management.
  • You are packaging/publishing the project itself → load build-and-release.
  • You suspect a dependency is malicious or vulnerable (supply-chain risk) → load security-review-playbook alongside this one.
  • You want to justify removing code/deps wholesale → load engineering-minimalism.

Core Methodology

Step 1 — Audit before adding (mandatory gate)

Run this decision tree BEFORE any pip install / npm install of a new package. (This is engineering-minimalism's decision ladder, rungs 1–5, specialized for dependencies — if that ladder changes, update this tree to match.)

Need capability X?
├── Does the stdlib do it? (json, pathlib, argparse, hashlib, urllib,
│   node:test, node:fs, crypto, std::collections ...)
│   └── YES → use stdlib. STOP. Zero new deps.
├── Does an ALREADY-INSTALLED dependency do it?
│   (grep the manifest; read its docs for the sub-feature)
│   └── YES → use it. STOP.
├── Can you write it in <50 lines with no edge-case landmines?
│   └── YES → write it. STOP. (Do NOT hand-roll crypto, parsers for
│       hostile input, or date/TZ math — those are landmines.)
└── Otherwise → add the dependency, but:
    ├── prefer small, single-purpose, actively maintained packages
    ├── record WHY in the commit message or a manifest comment
    └── choose the constraint via Step 3

Step 2 — Read the current state

  1. Locate the manifest and lock file (see Discovery Commands).
  2. Distinguish constraints (what you declared: pyproject.toml, package.json) from resolution (what actually installed: lock file, pip freeze).
  3. If there is no lock file (common in small Python projects), the manifest constraints ARE the reproducibility mechanism — they must carry tighter, more deliberate bounds.

Step 3 — Choose the constraint (narrow vs wide)

Decision rules, in order:

  1. Library you publish for others → widest safe range. Over-pinning a published library forces resolver conflicts on consumers.
  2. Application only you deploy → pin as tightly as needed for reproducibility; a lock file is ideal, exact pins the fallback.
  3. Dep with breaking minor releases, or whose API you touch deeply → narrow pin with upper bound (e.g. somelib>=1.4.0,<1.5.0).
  4. Fast-moving dep where you use a small stable API surface → floating lower bound, no upper bound (e.g. fastlib>=0.3).
  5. Known-bad future version → explicit ceiling (e.g. numpy<2.0) plus a documented reason.

Step 4 — Document WHY every pin exists

A pin without a reason is a trap: nobody knows when it can be lifted.

  • Put the reason in the commit message ("Pin numpy for chromadb 0.4"), a manifest comment, or the README.
  • The reason must name the lift condition ("remove when we move to chromadb >=0.5").

Step 5 — Diagnose transitive breakage

When installs break without a code change:

  1. Reproduce in a clean environment (fresh venv / delete node_modules and reinstall).
  2. Read the full traceback — the failing import names the guilty package, which is often NOT one you declared.
  3. List the resolved tree (pip freeze, npm ls <pkg>, pnpm why <pkg>, cargo tree -i <pkg>) and find which of YOUR deps pulls it in.
  4. Check whether the intermediate package declares an upper bound on the culprit. If it does not (e.g. chromadb 0.4 never declared numpy<2), the fix is to pin the transitive dep YOURSELF in your own manifest.
  5. Expect fix-after-fix: pinning the direct dep may not be enough; re-test a clean install after each pin.

Pre-merge checklist (any manifest change)

  • Audit ladder (Step 1) was run and the outcome noted.
  • Constraint style chosen deliberately (name the Step 3 rule number).
  • Every new pin/ceiling has a written WHY and a lift condition.
  • Clean-environment install succeeds (pip install -e . in a fresh venv, or npm ci after deleting node_modules).
  • Tests pass after the clean install.
  • Lock file (if the ecosystem has one) regenerated and committed with the manifest.
  • Supported runtime versions still accurate (e.g. README's Python range).

Discovery Commands

# Find manifests and lock files (any repo)
ls pyproject.toml setup.py requirements*.txt package.json pnpm-lock.yaml \
   package-lock.json yarn.lock Cargo.toml Cargo.lock poetry.lock 2>/dev/null
find . -maxdepth 2 \( -name pyproject.toml -o -name package.json \) -not -path "*/node_modules/*"

# Read declared constraints
grep -A 20 "dependencies" pyproject.toml          # Python
grep -A 30 '"dependencies"' package.json          # Node
grep -A 20 "\[dependencies\]" Cargo.toml          # Rust

# What actually resolved (constraints vs reality)
pip freeze                                        # Python: full resolved set
python3 -m pip show <pkg>                         # version + Requires/Required-by
npm ls <pkg>                                      # Node: who pulls it in
pnpm why <pkg>                                    # pnpm variant
cargo tree -i <pkg>                               # Rust: inverted dep tree

# History of dependency decisions (the WHYs live here)
git log --oneline -- pyproject.toml package.json Cargo.toml
git log -p pyproject.toml                         # read pin commits in full

# Clean-room reproduction
python3 -m venv /tmp/cleanenv && /tmp/cleanenv/bin/pip install -e .   # Python
rm -rf node_modules && npm ci                                          # Node (or: pnpm install --frozen-lockfile)

Failure Modes & Anti-patterns

SymptomMistakeCorrection
Fresh install crashes; code unchangedAssuming your declared deps are the problemRead the traceback; the culprit is often transitive. Trace with pip show / npm ls, then pin it yourself.
Pin nobody dares to removePinning without documenting whyEvery pin gets a written reason + lift condition (commit msg, comment, or README).
Consumers hit resolver conflictsExact-pinning everything in a published libraryLibraries get wide ranges; applications get locks/pins.
"Upgrade everything" PR breaks 3 thingsBulk-floating all constraints at onceUpgrade one dep per commit; clean install + tests between each.
New 40-package subtree for one functionSkipping the stdlib/existing-dep auditRun the Step 1 ladder; e.g. Node's native test runner replaces jest for small CLIs.
Works on your machine, breaks in fresh cloneRelying on a polluted long-lived venv/node_modulesVerify in a clean environment before declaring done.
One pin fixed it — broke again next weekBelieving the first fix is completeTransitive breakage is often fix-after-fix; re-verify clean install after each pin.
Package fails only on newest Python/NodeIgnoring wheel/runtime-support lagDocument the supported runtime range in README; ceiling the runtime, not just the package.

Repository Examples

ragit — the transitive-pin incident (as of 2026-07-04)

~/ragit: local RAG CLI (typer, Ollama embeddings, ChromaDB), installed via python3 -m pip install -e .. No lock file — constraints are hard-coded in pyproject.toml (re-read and verified this date):

typer>=0.12.3, rich>=13.7.1, ollama>=0.3.3,
chromadb>=0.4.0,<0.5.0, numpy<2.0, pypdf>=3.0.1, python-docx>=1.1.2
requires-python = ">=3.10"

The incident: chromadb 0.4 does NOT declare numpy<2; numpy 2.0 breaks it at runtime. The project pinned the TRANSITIVE dep itself, in two successive commits — a1ad63ed "Pin chromadb to 0.4.x" then 0a06ae9b "Pin numpy for chromadb 0.4 and add demo GIF" — a real fix-after-fix sequence (Step 5). Both constraint styles coexist deliberately in one file: narrow pin for the API-unstable dep (chromadb <0.5.0, Rule 3) beside a floating lower bound for the fast-moving one (ollama>=0.3.3, Rule 4). README documents Python 3.10–3.13 because "some vector DB dependencies may not publish wheels for very new Python versions yet". Full history arc: 4eed67ea initial → 3f88ce8d remove generated metadata → 57f95afd packaging keywords → fc3f8a43 "Switch to pypdf and fix README setup/details" → a1ad63ed → 0a06ae9b.

agentix — the same pin, independently (as of 2026-07-04)

~/agentix (hatchling build backend, pip install -e ".[dev]") declares numpy>=1.26.0,<2.0 — the same numpy-2 ceiling as ragit, confirming this is a class of problem, not a one-off. Other deps stay minimal and floating: beautifulsoup4>=4.12.0, httpx>=0.27.0.

NYTW — zero-dep testing (as of 2026-07-04)

~/NYTW: quiz tests run via npm test in quiz/ using Node's NATIVE test runner — zero added test dependencies. The Step 1 ladder ("stdlib does it?") applied to tooling, not just runtime deps.

Validation Criteria

You applied this skill correctly if:

  1. For any dependency you added, you can state which audit-ladder rung it passed (and which it failed).
  2. Every version ceiling/pin in the manifest has a discoverable WHY and lift condition.
  3. A newcomer can run one clean-environment install command from the README and get a working project.
  4. When diagnosing breakage, you named the exact transitive package AND the intermediate dep that pulls it in, before editing anything.
  5. The diff touching the manifest also updated the lock file (if any) and passed tests in a clean environment.

Provenance & Maintenance

  • Sources: ~/ragit, ~/agentix, ~/NYTW — investigated 2026-07-04. ragit's pyproject.toml was re-read byte-for-byte during authoring; agentix and NYTW facts come from the 2026-07-04 verified fact pack (their directories were read-restricted during authoring, so treat them as "verified 2026-07-04, not re-read").
  • Assumptions: ragit git hashes come from the 2026-07-04 investigation; if history is rewritten they drift. Methodology sections are repo-agnostic; repo facts are examples only, never baked-in assumptions.
  • Re-verification commands:
    grep -A 10 dependencies ~/ragit/pyproject.toml
    git -C ~/ragit log --oneline
    grep -rn "numpy" ~/agentix/pyproject.toml
    grep -n "test" ~/NYTW/quiz/package.json
  • Likely to drift: ragit's numpy/chromadb pins (should lift when chromadb >=0.5 is adopted); the Python 3.10–3.13 wheel-lag note; NYTW's zero-test-dep status if a framework is ever added.
  • Maintenance checklist: re-run re-verification commands; confirm each quoted pin still exists and still has a live reason; update commit hashes if history changed; keep the Step 1 audit ladder unchanged unless the minimalism doctrine itself changes.

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.