Dependency Evaluator Skill

This skill helps evaluate whether a programming language dependency should be added to a project by analyzing multiple quality signals and risk factors.

Purpose

Making informed decisions about dependencies is critical for project health. A poorly chosen dependency can introduce security vulnerabilities, maintenance burden, and technical debt. This skill provides a systematic framework for evaluating dependencies before adoption.

When to Use

Activate this skill when users:

• •Ask about whether to use a specific package/library
• •Want to evaluate a dependency before adding it
• •Need to compare alternative packages
• •Ask "should I use X library?"
• •Want to assess the health of a dependency
• •Mention adding a new npm/pip/cargo/gem/etc. package
• •Ask about package recommendations for a use case

Reference Files

This skill uses progressive disclosure - core framework below, detailed guidance in reference files:

Quick navigation by ecosystem:

• •npm → COMMANDS.md § Node.js + ECOSYSTEM_GUIDES.md § npm
• •PyPI → COMMANDS.md § Python + ECOSYSTEM_GUIDES.md § PyPI
• •Cargo → COMMANDS.md § Rust + ECOSYSTEM_GUIDES.md § Cargo
• •Go → COMMANDS.md § Go + ECOSYSTEM_GUIDES.md § Go
• •Other → COMMANDS.md for ecosystem-specific commands

Evaluation Framework

Evaluate dependencies using these ten key signals:

1. •Activity and Maintenance Patterns - Commit history, release cadence, issue responsiveness
2. •Security Posture - CVE history, security policies, vulnerability response time
3. •Community Health - Contributor diversity, PR merge rates, bus factor
4. •Documentation Quality - API docs, migration guides, examples
5. •Dependency Footprint - Transitive dependencies, bundle size
6. •Production Adoption - Download stats, notable users, trends
7. •License Compatibility - License type, transitive license obligations
8. •API Stability - Breaking change frequency, semver adherence
9. •Bus Factor and Funding - Organizational backing, sustainability
10. •Ecosystem Momentum - Framework alignment, technology trends

For detailed investigation guidance, see SIGNAL_DETAILS.md. For ecosystem-specific commands, see COMMANDS.md. For ecosystem considerations, see ECOSYSTEM_GUIDES.md.

Evaluation Approach

Goal: Provide evidence-based recommendations (ADOPT / EVALUATE FURTHER / AVOID) by systematically assessing 10 quality signals.

Process: Quick assessment → Data gathering → Scoring → Report generation

See WORKFLOW.md for detailed step-by-step guidance, performance tips, and workflow variants.

Automated Data Gathering (Recommended)

A Python script (scripts/dependency_evaluator.py) automates initial data gathering for supported ecosystems (npm, pypi, cargo, go). The script:

• •Runs ecosystem commands automatically
• •Fetches GitHub API data
• •Outputs structured JSON
• •Uses only Python standard library (no external dependencies)
• •Saves 10-15 minutes per evaluation

Default approach: Try the script first - it provides more complete and consistent data gathering. Only fall back to manual workflow if the script is unavailable or fails.

Use the script when: Evaluating npm, PyPI, Cargo, or Go packages (most common ecosystems) Use manual workflow when: Unsupported ecosystem, Python unavailable, or script errors occur

See SCRIPT_USAGE.md for complete documentation. The skill works perfectly fine without the script using manual workflow.

Before You Evaluate: Is a Dependency Needed?

Write it yourself if: Functionality is <50 lines of straightforward code, or you only need a tiny subset of features.

Use a dependency if: Problem is complex (crypto, dates, parsing), correctness is critical, or ongoing maintenance would be significant.

See WORKFLOW.md § Pre-Evaluation for detailed decision framework.

Output Format

Structure your evaluation report as:

## Dependency Evaluation: <package-name>

### Summary
[2-3 sentence overall assessment with recommendation]

**Recommendation**: [ADOPT / EVALUATE FURTHER / AVOID]
**Risk Level**: [Low / Medium / High]
**Blockers Found**: [Yes/No]

### Blockers (if any)
[List any dealbreaker issues - these override all scores]
- ⛔ [Blocker description with specific evidence]

### Evaluation Scores

| Signal | Score | Weight | Notes |
|--------|-------|--------|-------|
| Maintenance | X/5 | [H/M/L] | [specific evidence with dates/versions] |
| Security | X/5 | [H/M/L] | [specific evidence] |
| Community | X/5 | [H/M/L] | [specific evidence] |
| Documentation | X/5 | [H/M/L] | [specific evidence] |
| Dependency Footprint | X/5 | [H/M/L] | [specific evidence] |
| Production Adoption | X/5 | [H/M/L] | [specific evidence] |
| License | X/5 | [H/M/L] | [specific evidence] |
| API Stability | X/5 | [H/M/L] | [specific evidence] |
| Funding/Sustainability | X/5 | [H/M/L] | [specific evidence] |
| Ecosystem Momentum | X/5 | [H/M/L] | [specific evidence] |

**Weighted Score**: X/50 (adjusted for dependency criticality)

### Key Findings

#### Strengths
- [Specific strength with evidence]
- [Specific strength with evidence]

#### Concerns
- [Specific concern with evidence]
- [Specific concern with evidence]

### Alternatives Considered
[If applicable, mention alternatives worth evaluating]

### Recommendation Details
[Detailed reasoning for the recommendation with specific evidence]

### If You Proceed (for ADOPT recommendations)
[Specific advice tailored to risks found]
- Version pinning strategy
- Monitoring recommendations
- Specific precautions based on identified concerns

Scoring Weights

Adjust signal weights based on dependency type:

Critical Dependencies: Auth, security, data handling - require higher bar for all signals

Standard Dependencies: Utilities, formatting - balance all signals

Development Dependencies: Testing, linting - lower security concerns, focus on maintainability

Score Interpretation Rules

Blocker Override: Any blocker issue → AVOID recommendation regardless of scores

Critical Thresholds:

• •Security or Maintenance score ≤ 2 → Strongly reconsider regardless of other scores
• •Any High-weight signal ≤ 2 → Flag as significant concern in report
• •Overall weighted score < 25 → Default to EVALUATE FURTHER or AVOID
• •Overall weighted score ≥ 35 → Generally safe to ADOPT (if no blockers)

Weighting Priority: Security and Maintenance typically matter more than Documentation or Ecosystem Momentum. A well-documented but unmaintained package is riskier than a poorly-documented but actively maintained one.

Critical Red Flags (Dealbreakers)

These issues trigger automatic AVOID recommendation:

Supply Chain Risks

• •⛔ Typosquatting: Package name suspiciously similar to popular package
• •⛔ Compiled binaries without source: Binary blobs without build instructions
• •⛔ Sudden ownership transfer: Recent transfer to unknown maintainer
• •⛔ Install scripts with network calls: Postinstall scripts downloading external code

Maintainer Behavior

• •⛔ Ransom behavior: Maintainer demanding payment to fix security issues
• •⛔ Protest-ware: Code performing actions based on political/geographic conditions
• •⛔ Intentional sabotage history: Any history of deliberately breaking the package

Security Issues

• •⛔ Active exploitation: Known vulnerability being actively exploited in wild
• •⛔ Credentials in source: API keys, passwords, or secrets in repository
• •⛔ Disabled security features: Package disables security without clear reason

Legal Issues

• •⛔ License violation: Package includes code violating its stated license
• •⛔ No license: No license file means all rights reserved (legally risky)
• •⛔ License change without notice: Recent sneaky change to restrictive terms

Self-Validation Checklist

Before presenting your report, verify:

• • Cited specific versions and dates for all claims?
• • Ran actual commands rather than making assumptions?
• • All scores supported by evidence in "Notes" column?
• • If Security or Maintenance ≤ 2, flagged prominently?
• • If any blocker exists, recommendation is AVOID?
• • Provided at least 2 alternatives if recommending AVOID?
• • "If You Proceed" section tailored to specific risks found?
• • Recommendation aligns with weighted score and blocker rules?

Evaluation Principles

Be Evidence-Based: Cite specific versions, dates, and metrics. Run commands to gather data, never assume.

Be Balanced: Acknowledge strengths AND weaknesses. Single issues rarely disqualify (unless blocker).

Be Actionable: Provide clear ADOPT/EVALUATE FURTHER/AVOID with alternatives and risk mitigation.

Be Context-Aware: Auth libraries need stricter scrutiny than dev tools. Adjust for ecosystem norms (see ECOSYSTEM_GUIDES.md).

See WORKFLOW.md § Common Pitfalls and § Guidelines for detailed best practices.