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
In this repository25 other files it gives its agents.
- Agent EngineeringSkill
- API and Interface DesignSkill
- Architecture AnalysisSkill
- Build and ReleaseSkill
- Campaign PlanningSkill
- Change ControlSkill
- Codebase OnboardingSkill
- Code Review PlaybookSkill
- Configuration ManagementSkill
- Debugging PlaybookSkill
- Documentation PracticesSkill
- Engineering MinimalismSkill
- Evaluation FrameworksSkill
- Failure ArchaeologySkill
- LLM Integration ReliabilitySkill
- LLM System DesignSkill
- Observability and DiagnosticsSkill
- Performance EngineeringSkill
- Prompt and Context EngineeringSkill
- Proof and AnalysisSkill
- Refactoring PlaybookSkill
- Research MethodologySkill
- Security Review PlaybookSkill
- System DesignSkill
- Validation And TestingSkill
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
- Very specific: line 32
Run this decision tree BEFORE any pip install / npm install of a new package.
- Distinctive: line 55
If there is no lock file (common in small Python projects), the manifest constraints ARE the reproducibility mechanism — they must carry …
- Distinctive: line 70
Put the reason in the commit message ("Pin numpy for chromadb 0.4"), a manifest comment, or the README.
- Distinctive: line 75
When installs break without a code change:
- Distinctive: line 78
Read the full traceback — the failing import names the guilty package, which is often NOT one you declared.
- Very specific: line 80
Check whether the intermediate package declares an upper bound on the culprit.
- Distinctive: line 161
Every version ceiling/pin in the manifest has a discoverable WHY and lift condition.
- Distinctive: line 163
When diagnosing breakage, you named the exact transitive package AND the intermediate dep that pulls it in, before editing anything.
≈ “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.
Files
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-playbookalongside 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 3Step 2 — Read the current state
- Locate the manifest and lock file (see Discovery Commands).
- Distinguish constraints (what you declared:
pyproject.toml,package.json) from resolution (what actually installed: lock file,pip freeze). - 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:
- Library you publish for others → widest safe range. Over-pinning a published library forces resolver conflicts on consumers.
- Application only you deploy → pin as tightly as needed for reproducibility; a lock file is ideal, exact pins the fallback.
- 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). - Fast-moving dep where you use a small stable API surface → floating lower bound, no upper bound (e.g.
fastlib>=0.3). - 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:
- Reproduce in a clean environment (fresh venv / delete
node_modulesand reinstall). - Read the full traceback — the failing import names the guilty package, which is often NOT one you declared.
- 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. - 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. - 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, ornpm ciafter 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
| Symptom | Mistake | Correction |
| Fresh install crashes; code unchanged | Assuming your declared deps are the problem | Read the traceback; the culprit is often transitive. Trace with pip show / npm ls, then pin it yourself. |
| Pin nobody dares to remove | Pinning without documenting why | Every pin gets a written reason + lift condition (commit msg, comment, or README). |
| Consumers hit resolver conflicts | Exact-pinning everything in a published library | Libraries get wide ranges; applications get locks/pins. |
| "Upgrade everything" PR breaks 3 things | Bulk-floating all constraints at once | Upgrade one dep per commit; clean install + tests between each. |
| New 40-package subtree for one function | Skipping the stdlib/existing-dep audit | Run the Step 1 ladder; e.g. Node's native test runner replaces jest for small CLIs. |
| Works on your machine, breaks in fresh clone | Relying on a polluted long-lived venv/node_modules | Verify in a clean environment before declaring done. |
| One pin fixed it — broke again next week | Believing the first fix is complete | Transitive breakage is often fix-after-fix; re-verify clean install after each pin. |
| Package fails only on newest Python/Node | Ignoring wheel/runtime-support lag | Document 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:
- For any dependency you added, you can state which audit-ladder rung it passed (and which it failed).
- Every version ceiling/pin in the manifest has a discoverable WHY and lift condition.
- A newcomer can run one clean-environment install command from the README and get a working project.
- When diagnosing breakage, you named the exact transitive package AND the intermediate dep that pulls it in, before editing anything.
- 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.tomlwas 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.
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
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.

