Agent Skills: Cargo Knowledge Patch

Cargo Knowledge Patch

Use this skill when working on Cargo manifests, configuration, workspaces, dependency resolution, packaging, publishing, build scripts, or unstable Cargo tooling. First determine the project's Cargo version, Rust edition, MSRV, workspace shape, target platforms, and enabled -Z flags. Apply guidance only when the installed Cargo is new enough for it.

Reference index

| Reference | Topics | | --- | --- | | build-configuration-and-artifacts.md | Layered configuration, cache cleanup, target selection, build directories, warnings, artifacts, platform behavior | | commands-workspaces-and-dependencies.md | Edition migration, workspaces, fix, tree, metadata, clean, dependency and target commands | | packaging-publishing-and-registries.md | Package validation, lockfiles, reproducibility, workspace publishing, registries, Git and SSH transport | | scripts-build-scripts-and-environment.md | Cargo scripts, multiple build scripts, Cargo-provided environment variables, link arguments and script state | | nightly-and-structured-tooling.md | Unstable feature flags, build analysis, Cargo lints, SBOM precursors, unit graphs, rustdoc and lockfile experiments |

Apply this patch

1. Read rust-version, edition, workspace resolver settings, and any cargo-features declaration from the manifests.
2. Check cargo --version; unstable behavior also depends on the selected nightly toolchain and the exact -Z flags.
3. Inspect .cargo/config.toml, environment variables, and CLI --config values as separate configuration layers.
4. Identify whether commands run against a virtual workspace, a selected package, the host, or a cross-compiled target.
5. Treat the target directory, intermediate build directory, package archive, and persistent analysis logs as distinct artifact locations.
6. For publishing, check registry credentials, package dirtiness, lockfile policy, workspace dependency order, and whether a local .crate archive is required.
7. For build scripts and Cargo scripts, distinguish compile-time environment, runtime environment, per-script output directories, and script-local state.

Breaking changes and deprecations

Patch vulnerable Cargo installations

Cargo 1.94 fixes CVE-2026-33055 and CVE-2026-33056. On Unix-like systems, earlier affected versions can let a malicious crate archive alter permissions on arbitrary filesystem paths during extraction. Upgrade Cargo before fetching or unpacking untrusted crates.

Update removed unstable interfaces

• The unstable build-plan feature is gone. Use plumbing commands, --unit-graph, or structured -Zbuild-analysis logs.
• --timings=<FMT> is gone. Use build-analysis data for machine-readable timings or cargo report timings for HTML.
• The deprecated unstable --out-dir is gone; use --artifact-dir.
• The unstable --lockfile-path CLI option is gone. Under -Zlockfile-path, configure resolver.lockfile-path.

Do not rely on cargo publish retaining archives

cargo publish no longer leaves the .crate tarball as a final local artifact. Run cargo package when a workflow needs the archive. Publishing several workspace packages is not atomic: a server failure may leave only a prefix of the requested packages published.

Recheck fix-command target scope

cargo fix and cargo clippy --fix operate on default targets unless --all-targets is passed. Edition and edition-idiom migrations still imply all targets. Also, cargo fix --allow-dirty now implies --allow-staged.

cargo fix --all-targets
cargo clippy --fix --all-targets

Replace deprecated manifest and configuration forms

• Move a deprecated <target>.edition setting to the package-level edition.
• Avoid cargo publish --token in new workflows.
• Make install.root absolute or use a trailing slash while migrating away from working-directory-relative interpretation.
• Do not put a trailing slash on a registry config.json api URL.
• Spell keyword-named cfg identifiers as raw identifiers, such as cfg(r#true), when identifier semantics are intended.

High-value stable behavior

Rust 2024 and manifest parsing

Cargo supports edition = "2024", and cargo fix --edition migrates workspace dependencies declared in virtual manifests. Cargo 1.94 parses TOML 1.1 in manifests and configuration; using TOML 1.1 syntax in Cargo.toml raises the development MSRV even though the manifest emitted for publication remains compatible with older parsers.

[package]
edition = "2024"

Intermediate build directories

build.build-dir is stable. It separates intermediate Cargo and rustc files from the target directory, but its internal layout is not public and may change. Trimmed paths remap to this directory. When tools need its resolved location, read build_directory from cargo metadata.

[build]
build-dir = "build"

Warning policy

Cargo 1.97 honors build.warnings = "warn" | "allow" | "deny" and CARGO_BUILD_WARNINGS; the default is warn. The policy does not alter compiler flags used to identify cached artifacts. deny makes warnings and warning summaries fail the build unless --keep-going allows other work to continue. allow cannot conceal denied diagnostics or hard warnings.

[build]
warnings = "deny"

Configuration includes

The top-level include key is stable and can split shared Cargo configuration across files. The earlier unstable optional form requires list syntax:

include = [{ path = "local.toml", optional = true }]

An optional missing file is skipped. include.path does not accept glob or template syntax.

Host target shorthand

Use host-tuple in --target, build.target, and cargo metadata --filter-platform when the current machine's host triple is needed without hard-coding it.

cargo build --target host-tuple
cargo metadata --filter-platform host-tuple

Workspace operations

• cargo tree --depth workspace limits output to workspace members.
• cargo clean --workspace removes artifacts belonging to workspace members.
• cargo tree --format accepts long variables such as {package} and {features}.
• --package combined with --workspace errors if a requested package is missing.

cargo tree --depth workspace
cargo clean --workspace
cargo tree --format '{package} {features}'

Safer command conveniences

-m is an alias for --manifest-path. cargo clean --target-dir refuses a path that does not look like a Cargo target directory. cargo init refuses to initialize the user's home directory. With no explicit registry, cargo info defaults to the local package.

cargo build -m path/to/Cargo.toml

Packaging and registry checklist

• cargo package includes Cargo.lock; --exclude-lockfile stops verification of an existing lockfile.
• Package validation examines external readme, license-file, and symlink targets, and reports a dirty workspace manifest.
• Generated package files have deterministic timestamps.
• Multi-package publishing supports --workspace and repeated -p, but is non-atomic.
• Registry HTTP 429 responses honor Retry-After.
• Registry index consumers must tolerate a missing pubtime while historical entries are being backfilled.
• cargo vendor preserves .rej and .orig and directly extracts registry sources so vendored files match their originals.

Build scripts and Cargo scripts

• Build scripts receive activated features in CARGO_CFG_FEATURE and profile debug-assertion state in CARGO_CFG_DEBUG_ASSERTIONS.
• With multiple build scripts, each script gets <script-name>_OUT_DIR.
• CARGO_BIN_EXE_<name> is available at runtime as well as compile time.
• The CARGO value is the invoked Cargo path and may retain symlinks; external subcommands must not treat it as a general-purpose wrapper.
• Cargo script manifests have strict frontmatter fences, default bin.name to package.name, load configuration relative to the script, and use script-specific lockfiles.

Unstable-feature discipline

Unstable Cargo flags evolve quickly. Keep each -Z opt-in explicit in CI, check the exact toolchain before consuming structured output, and avoid depending on experimental filesystem layouts. In particular:

• Public dependency trees use --edges public; the older --depth public spelling was replaced.
• -Zbuild-analysis writes one JSONL log per invocation under ~/.cargo/log/ and supports cargo report sessions, rebuilds, and timings.
• -Zcargo-lints has lint groups and independent explicit-level precedence.
• -Zlockfile-path does not redirect cargo install; install intentionally ignores the configured path.
• -Zbuild-std accepts comma-separated components and excludes implicit standard-library crates from unused_crate_dependencies.

Consult the topic references before changing an unstable workflow; they record the transitions and the structured fields consumers must parse.