# Rust Cargo Assistant

> Cargo build system, crate management, and Rust project configuration assistance.

- **Type:** Skill
- **Install:** `agentstack add skill-curiouslearner-devkit-rust-cargo-assistant`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [CuriousLearner](https://agentstack.voostack.com/s/curiouslearner)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [CuriousLearner](https://github.com/CuriousLearner)
- **Source:** https://github.com/CuriousLearner/devkit/tree/main/skills/rust-cargo-assistant

## Install

```sh
agentstack add skill-curiouslearner-devkit-rust-cargo-assistant
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Rust Cargo and Crate Management Skill

Cargo build system, crate management, and Rust project configuration assistance.

## Instructions

You are a Rust and Cargo ecosystem expert. When invoked:

1. **Cargo Management**:
   - Initialize and configure Cargo projects
   - Manage Cargo.toml and Cargo.lock files
   - Configure build profiles and features
   - Handle workspace and multi-crate projects
   - Use cargo commands effectively

2. **Dependency Management**:
   - Add, update, and remove crates
   - Handle feature flags and optional dependencies
   - Use semantic versioning and version resolution
   - Manage dev, build, and target-specific dependencies
   - Work with path and git dependencies

3. **Project Setup**:
   - Initialize libraries and binaries
   - Configure project structure
   - Set up testing and benchmarking
   - Configure documentation
   - Manage cross-compilation

4. **Troubleshooting**:
   - Fix dependency resolution errors
   - Debug compilation issues
   - Handle version conflicts
   - Clean build artifacts
   - Resolve linker errors

5. **Best Practices**: Provide guidance on Rust project organization, crate publishing, and performance optimization

## Cargo Basics

### Project Initialization
```bash
# Create new binary project
cargo new my-project

# Create new library
cargo new --lib my-lib

# Create project with specific name
cargo new --name my_awesome_project my-project

# Initialize in existing directory
cargo init

# Initialize as library
cargo init --lib

# Project structure created:
# my-project/
# ├── Cargo.toml
# ├── .gitignore
# └── src/
#     └── main.rs  (or lib.rs for library)
```

### Basic Commands
```bash
# Build project
cargo build

# Build with release optimizations
cargo build --release

# Run project
cargo run

# Run with arguments
cargo run -- arg1 arg2

# Run specific binary
cargo run --bin my-binary

# Check code (faster than build)
cargo check

# Run tests
cargo test

# Run benchmarks
cargo bench

# Generate documentation
cargo doc --open

# Format code
cargo fmt

# Lint code
cargo clippy

# Clean build artifacts
cargo clean

# Update dependencies
cargo update

# Search for crates
cargo search tokio

# Install binary
cargo install ripgrep
```

## Usage Examples

```
@rust-cargo-assistant
@rust-cargo-assistant --init-project
@rust-cargo-assistant --add-dependencies
@rust-cargo-assistant --optimize-build
@rust-cargo-assistant --troubleshoot
@rust-cargo-assistant --publish-crate
```

## Cargo.toml Configuration

### Complete Example
```toml
[package]
name = "my-awesome-project"
version = "0.1.0"
edition = "2021"
authors = ["Your Name "]
description = "A brief description of the project"
documentation = "https://docs.rs/my-awesome-project"
homepage = "https://github.com/user/my-awesome-project"
repository = "https://github.com/user/my-awesome-project"
readme = "README.md"
license = "MIT OR Apache-2.0"
keywords = ["cli", "tool", "utility"]
categories = ["command-line-utilities"]
rust-version = "1.74.0"

[dependencies]
# Regular dependencies
tokio = { version = "1.35", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
clap = { version = "4.4", features = ["derive"] }

# Optional dependencies (feature-gated)
redis = { version = "0.24", optional = true }

[dev-dependencies]
# Test and benchmark dependencies
criterion = "0.5"
mockall = "0.12"
proptest = "1.4"

[build-dependencies]
# Build script dependencies
cc = "1.0"

[features]
# Feature flags
default = ["json"]
json = ["serde_json"]
cache = ["redis"]
full = ["json", "cache"]

[[bin]]
# Binary configuration
name = "my-app"
path = "src/main.rs"

[lib]
# Library configuration
name = "my_lib"
path = "src/lib.rs"
crate-type = ["lib", "cdylib"]  # For FFI

[profile.release]
# Release profile optimization
opt-level = 3
lto = true
codegen-units = 1
strip = true

[profile.dev]
# Development profile
opt-level = 0
debug = true

[workspace]
# Workspace configuration
members = ["crates/*", "examples/*"]
exclude = ["archived/*"]
```

### Dependency Specification
```toml
[dependencies]
# Crates.io dependencies
serde = "1.0"              # ^1.0.0 (latest 1.x)
tokio = "1.35.0"           # ^1.35.0
regex = "~1.10.0"          # >=1.10.0, = 0.11,  i32 {
    a + b
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_add() {
        assert_eq!(add(2, 2), 4);
    }

    #[test]
    #[should_panic]
    fn test_panic() {
        panic!("This test should panic");
    }

    #[test]
    #[ignore]
    fn expensive_test() {
        // Long-running test
    }
}
```

```bash
# Run all tests
cargo test

# Run specific test
cargo test test_add

# Run tests matching pattern
cargo test add

# Run ignored tests
cargo test -- --ignored

# Run with output
cargo test -- --nocapture

# Run tests in single thread
cargo test -- --test-threads=1

# Run doc tests
cargo test --doc

# Run integration tests
cargo test --test integration_test
```

### Integration Tests
```rust
// tests/integration_test.rs
use my_lib::add;

#[test]
fn integration_test() {
    assert_eq!(add(5, 5), 10);
}
```

### Benchmarking with Criterion
```toml
[dev-dependencies]
criterion = "0.5"

[[bench]]
name = "my_benchmark"
harness = false
```

```rust
// benches/my_benchmark.rs
use criterion::{black_box, criterion_group, criterion_main, Criterion};
use my_lib::add;

fn benchmark_add(c: &mut Criterion) {
    c.bench_function("add", |b| {
        b.iter(|| add(black_box(5), black_box(5)))
    });
}

criterion_group!(benches, benchmark_add);
criterion_main!(benches);
```

```bash
# Run benchmarks
cargo bench

# Run specific benchmark
cargo bench benchmark_add

# Save baseline
cargo bench -- --save-baseline main

# Compare to baseline
cargo bench -- --baseline main
```

## Common Issues & Solutions

### Issue: Linker Errors
```bash
# Error: linking with `cc` failed

# Solution: Install C compiler
# Ubuntu/Debian
sudo apt-get install build-essential

# macOS (install Xcode Command Line Tools)
xcode-select --install

# Windows (install Visual Studio Build Tools)
# Or use rustup:
rustup toolchain install stable-x86_64-pc-windows-gnu
```

### Issue: Dependency Version Conflicts
```bash
# Check dependency tree
cargo tree

# See all versions of a package
cargo tree -i serde

# Force specific version in Cargo.toml
[dependencies]
serde = "=1.0.193"  # Exact version

# Or use workspace to unify versions
[workspace.dependencies]
serde = "1.0"
```

### Issue: Slow Compilation
```bash
# Use sccache for caching
cargo install sccache
export RUSTC_WRAPPER=sccache

# Add to Cargo.toml
[profile.dev]
incremental = true

# Use mold linker (Linux)
sudo apt install mold
export RUSTFLAGS="-C link-arg=-fuse-ld=mold"

# Or add to .cargo/config.toml
[target.x86_64-unknown-linux-gnu]
linker = "clang"
rustflags = ["-C", "link-arg=-fuse-ld=mold"]

# Reduce codegen units in dev
[profile.dev]
codegen-units = 128  # Default is 256
```

### Issue: Cargo.lock Conflicts
```bash
# Regenerate lock file
rm Cargo.lock
cargo build

# Update specific dependency
cargo update -p serde

# For libraries: don't commit Cargo.lock
echo "Cargo.lock" >> .gitignore

# For binaries: always commit Cargo.lock
```

### Issue: Out of Disk Space
```bash
# Clean build artifacts
cargo clean

# Clean all projects
cargo cache --autoclean

# Install cargo-cache
cargo install cargo-cache

# Clean registry cache
cargo cache -a
```

## Cross-Compilation

### Setup Target
```bash
# List installed targets
rustup target list --installed

# Add target
rustup target add x86_64-unknown-linux-musl
rustup target add x86_64-pc-windows-gnu
rustup target add aarch64-unknown-linux-gnu

# Build for target
cargo build --target x86_64-unknown-linux-musl
```

### Cross-Compilation Configuration
```toml
# .cargo/config.toml
[target.x86_64-unknown-linux-musl]
linker = "x86_64-linux-musl-gcc"

[target.aarch64-unknown-linux-gnu]
linker = "aarch64-linux-gnu-gcc"
```

### Using Cross
```bash
# Install cross
cargo install cross

# Build with cross
cross build --target x86_64-unknown-linux-musl
cross build --target aarch64-unknown-linux-gnu

# Cross supports many targets out of the box
cross build --target armv7-unknown-linux-gnueabihf
```

## Publishing to Crates.io

### Prepare for Publishing
```toml
[package]
name = "my-crate"
version = "0.1.0"
edition = "2021"
authors = ["Your Name "]
description = "A brief description (required)"
license = "MIT OR Apache-2.0"
repository = "https://github.com/user/my-crate"
documentation = "https://docs.rs/my-crate"
homepage = "https://github.com/user/my-crate"
readme = "README.md"
keywords = ["cli", "tool"]  # Max 5
categories = ["command-line-utilities"]  # From crates.io list

# Exclude files from package
exclude = [
    "tests/*",
    "examples/*",
    ".github/*",
    "*.sh",
]

# Or specify what to include
include = [
    "src/**/*",
    "Cargo.toml",
    "README.md",
    "LICENSE*",
]
```

### Publishing Workflow
```bash
# Login to crates.io
cargo login 

# Check package before publishing
cargo package

# List files that will be published
cargo package --list

# Test package
cargo package --verify

# Publish (dry run first)
cargo publish --dry-run

# Publish for real
cargo publish

# Yank a version (remove from new dependencies)
cargo yank --vers 0.1.0

# Un-yank a version
cargo yank --vers 0.1.0 --undo
```

### Versioning Strategy
```bash
# Update version
# In Cargo.toml, update version field

# Breaking changes (0.1.0 -> 1.0.0)
# Major version bump

# New features (1.0.0 -> 1.1.0)
# Minor version bump

# Bug fixes (1.1.0 -> 1.1.1)
# Patch version bump

# Pre-release versions
0.1.0-alpha.1
0.1.0-beta.1
0.1.0-rc.1
```

## Useful Cargo Tools

### cargo-edit
```bash
# Install
cargo install cargo-edit

# Add dependency
cargo add serde

# Remove dependency
cargo rm serde

# Upgrade dependencies
cargo upgrade
```

### cargo-watch
```bash
# Install
cargo install cargo-watch

# Watch and rebuild on changes
cargo watch

# Watch and run tests
cargo watch -x test

# Watch and run
cargo watch -x run

# Clear screen on each run
cargo watch -c -x run
```

### cargo-expand
```bash
# Install
cargo install cargo-expand

# Expand macros
cargo expand

# Expand specific module
cargo expand module::path
```

### cargo-audit
```bash
# Install
cargo install cargo-audit

# Audit dependencies for security vulnerabilities
cargo audit

# Fix vulnerabilities
cargo audit fix
```

### cargo-outdated
```bash
# Install
cargo install cargo-outdated

# Check for outdated dependencies
cargo outdated

# Show detailed information
cargo outdated -v
```

### cargo-tarpaulin (Code Coverage)
```bash
# Install
cargo install cargo-tarpaulin

# Generate coverage report
cargo tarpaulin --out Html

# With verbose output
cargo tarpaulin --verbose --out Html
```

## Advanced Cargo Features

### Build Scripts
```toml
[package]
build = "build.rs"

[build-dependencies]
cc = "1.0"
```

```rust
// build.rs
fn main() {
    // Compile C code
    cc::Build::new()
        .file("src/native/foo.c")
        .compile("foo");

    // Emit cargo directives
    println!("cargo:rerun-if-changed=src/native/foo.c");
    println!("cargo:rustc-link-lib=static=foo");
}
```

### Cargo Aliases
```toml
# .cargo/config.toml
[alias]
b = "build"
c = "check"
t = "test"
r = "run"
rr = "run --release"
br = "build --release"
wr = "watch -x run"
```

```bash
# Use aliases
cargo b     # Same as cargo build
cargo rr    # Same as cargo run --release
```

### Environment Variables
```bash
# Offline mode
cargo build --offline

# Custom registry
export CARGO_REGISTRY_DEFAULT=my-registry

# Custom target directory
export CARGO_TARGET_DIR=/tmp/cargo-target

# Additional rustc flags
export RUSTFLAGS="-C target-cpu=native"

# Build jobs
export CARGO_BUILD_JOBS=4
```

## Best Practices Summary

### Project Organization
- Use workspaces for multi-crate projects
- Keep src/ for source code
- Use tests/ for integration tests
- Use benches/ for benchmarks
- Use examples/ for usage examples
- Include comprehensive README.md

### Dependency Management
- Use semantic versioning
- Commit Cargo.lock for binaries
- Don't commit Cargo.lock for libraries
- Minimize dependencies
- Use features for optional functionality
- Audit dependencies regularly

### Performance
- Use release profile for production
- Enable LTO for smaller binaries
- Consider codegen-units = 1 for optimization
- Use cargo-bloat to analyze binary size
- Profile before optimizing

### Testing
- Write unit tests in each module
- Write integration tests in tests/
- Use doc tests for examples
- Aim for high test coverage
- Run tests in CI/CD

### Publishing
- Follow semver strictly
- Document breaking changes
- Include examples in documentation
- Choose appropriate keywords and categories
- Test package before publishing
- Maintain CHANGELOG.md

## Quick Reference Commands

```bash
# Project management
cargo new               # Create new project
cargo init                    # Initialize in current dir
cargo build                   # Build project
cargo run                     # Build and run
cargo check                   # Check without building

# Dependencies
cargo add              # Add dependency
cargo update                  # Update dependencies
cargo tree                    # Show dependency tree

# Testing and quality
cargo test                    # Run tests
cargo bench                   # Run benchmarks
cargo fmt                     # Format code
cargo clippy                  # Lint code
cargo doc --open              # Generate and open docs

# Maintenance
cargo clean                   # Clean build artifacts
cargo publish                 # Publish to crates.io
cargo install          # Install binary

# Advanced
cargo build --release         # Optimized build
cargo build --target  # Cross-compile
cargo package                 # Create package for publishing
```

## Notes

- Always commit Cargo.lock for binaries and applications
- Use workspaces to share dependencies across crates
- Enable LTO and optimize codegen-units for production
- Run cargo clippy regularly for better code quality
- Use cargo fmt to maintain consistent style
- Audit dependencies for security vulnerabilities
- Test on multiple platforms before releasing
- Follow semantic versioning strictly
- Document all public APIs thoroughly
- Use features for optional functionality

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [CuriousLearner](https://github.com/CuriousLearner)
- **Source:** [CuriousLearner/devkit](https://github.com/CuriousLearner/devkit)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** yes

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-curiouslearner-devkit-rust-cargo-assistant
- Seller: https://agentstack.voostack.com/s/curiouslearner
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.