Managing Cargo Dependencies
Developmentmanaging-cargo-dependenciesManaging Cargo Dependencies is an Agent Skill for development published in the hashintel/hash repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Cargo.toml dependency management patterns for HASH workspace. Use when adding, updating, or removing dependencies, organizing Cargo.toml sections, configuring version pinning and default features, or managing public dependencies.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/hashintel/hash/blob/HEAD/.claude/skills/managing-cargo-dependencies/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/managing-cargo-dependencies, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Cargo Dependencies Management
Guidance for adding and managing dependencies in Cargo.toml files within the HASH repository's workspace structure.
Core Principles
HASH uses a strict workspace dependency pattern:
✅ DO:
- Add external dependencies to workspace root
[workspace.dependencies] - Use caret version specifiers (e.g.,
version = "1.0.0"=^1.0.0) - Set
default-features = falsefor all dependencies unless specifically needed - Use
workspace = truein package Cargo.toml - Organize dependencies into 4 sections with comment headers
- Use
public = truefor dependencies exposed in public API - Align dependency names using spaces for readability
❌ DON'T:
- Add version numbers directly in package Cargo.toml
- Use exact versions with
=prefix (e.g.,=1.0.0) in workspace root - Enable
default-featureswithout considering impact - Mix different dependency types without section comments
- Forget
public = truefor dependencies exposed in public API
Quick Reference
The 4-Section Pattern
Every package Cargo.toml must organize dependencies into these sections:
[dependencies]
# Public workspace dependencies
hash-graph-types = { workspace = true, public = true }
hashql-core = { workspace = true, public = true }
# Public third-party dependencies
serde = { workspace = true, public = true, features = ["derive"] }
tokio = { workspace = true, public = true }
# Private workspace dependencies
error-stack = { workspace = true }
hash-codec = { workspace = true }
# Private third-party dependencies
tracing = { workspace = true }
regex = { workspace = true }
Keep all 4 section comments even if a section is empty.
Quick Add Process
- Check workspace root - Is dependency already there?
- Add to workspace if needed - With caret version
1.2.3 - Determine section - Public workspace/third-party or private?
- Add to package - Use
workspace = true(+public = trueif needed)
Detailed Guides
Choose the guide that matches the task:
workspace-setup.md
Use when: Adding new dependencies to workspace root
- How to add external crates to workspace
- Version pinning with exact versions
- Default features configuration
- Workspace member paths
package-dependencies.md
Use when: Adding dependencies to a package Cargo.toml
- The 4-section organizational structure
- Public vs private dependencies
- When to use
public = true - Alignment and formatting rules
- Feature configuration
examples-reference.md
Use when: Looking for real examples from HASH codebase
- Complete examples from
@local/codec - Complete examples from
@local/hashql/core - Optional dependencies pattern
- dev-dependencies structure
Common Patterns
Adding a New External Dependency
# 1. Add to workspace root Cargo.toml
[workspace.dependencies]
my-crate = { version = "1.2.3", default-features = false }
# 2. Add to package Cargo.toml (appropriate section)
[dependencies]
# Private third-party dependencies
my-crate = { workspace = true }
Making a Dependency Public
# Use when the dependency appears in your public API
serde = { workspace = true, public = true, features = ["derive"] }
tokio = { workspace = true, public = true }
Optional Dependencies
[dependencies]
serde = { workspace = true, optional = true, features = ["derive"] }
[features]
serde = ["dep:serde", "other-dep/serde"]
References
- workspace-setup.md - Workspace root configuration
- package-dependencies.md - Package dependency structure
- examples-reference.md - Real codebase examples
- Workspace Cargo.toml - Root workspace configuration
- hash-codec/Cargo.toml - Reference example
- hashql-core/Cargo.toml - Reference example