New Rust Project

New Rust project (cargo)

Create a fresh Rust project with cargo new, then layer on a comprehensive .gitignore, MIT license, README, GitHub Actions CI/CD workflows, and per-step git commits.

Inputs

• project name (required) — directory + crate name.

Tool preference

Prefer language-native tooling (cargo) for anything it can generate; use npx generators (npx gitignore, npx license) where cargo has no equivalent; fall back to hand-written content or bundled reference files only when neither is available.

Partially set-up projects

This skill also finishes a project that is already partially set up. Every step is idempotent — before running a step, check whether its output already exists:

• If Cargo.toml already exists, skip cargo generation entirely (cargo new /

cargo init) and continue with the remaining steps.

• If the repo already has commits, skip the "New repo" empty commit.
• An artifact that already exists (LICENSE, README, a workflow file) is kept

as-is, not overwritten; skip that step and its commit.

• .gitignore is merged, not replaced: append only the missing entries

(including .vscode/).

• Only commit a step that actually changed something, keeping the same commit

messages.

Steps

Run these from the directory where the new project folder should live. Requires cargo and git on PATH.

1. Create and enter the project:

``bash cargo new cd ``

If the folder already exists, cargo new refuses to run — use it in place instead (cargo init names the crate after the directory and still runs git init when needed):

``bash cd cargo init ``

1. Seed an empty commit (cargo already ran git init):

``bash git commit --allow-empty -m "New repo" ``

1. .gitignore — cargo already seeded a minimal one; extend it with the

community Rust rules plus the editor dir (npx gitignore appends to an existing file, so nothing is lost):

``bash npx gitignore rust echo ".vscode/" >> .gitignore ``

The Rust rules ignore Cargo.lock with a comment explaining the choice — keep the entry for a library, delete it for an executable. If npx is unavailable, append these entries by hand instead:

```text debug/ target/

# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries # More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html Cargo.lock

# These are backup files generated by rustfmt **/*.rs.bk

# MSVC Windows builds of rustc generate these, which store debugging information *.pdb

.vscode/ ```

Then: git add .gitignore && git commit -m "Added .gitignore"

1. MIT license — generate it (npx license MIT writes LICENSE, filling the

year and the author from git config):

``bash npx license MIT ``

Verify the copyright line reads Copyright (c) and fix it up if not. If npx is unavailable, fall back to reference/mit-license.txt (this skill dir), replacing ` with the current year followed by the author from git config user.name. Then: git add LICENSE && git commit -m "Added MIT License"`

1. README: echo "# " > README.md, then

git add README.md && git commit -m "Added default README.md"

1. Commit the cargo manifest:

git add Cargo.toml && git commit -m "Added default Cargo.toml"

1. CI workflow — copy templates/ci.yml (this skill dir) to

.github/workflows/ci.yml. Replace @CRATE_NAME@ (in the docs job's redirect index) with the crate name — the name from Cargo.toml, which is the project name with - kept as written (cargo doc outputs to target/doc//; if the crate name contains -, substitute underscores, e.g. my-lib → my_lib).

The template uses: pins are a current-as-of-authoring baseline and may have gone stale. Before committing, resolve the latest stable major version of each versioned action and update its uses::

• actions/checkout
• Swatinem/rust-cache
• actions/configure-pages
• actions/upload-pages-artifact
• actions/deploy-pages
• codecov/codecov-action

Leave dtolnay/rust-toolchain@stable and taiki-e/install-action@cargo-llvm-cov as-is — they are pinned to a channel / tool name, not a version tag.

Resolve with git ls-remote (no gh, no auth):

``bash git ls-remote --tags --refs https://github.com/actions/checkout 'v*' ``

Take the highest stable semver (ignore tags containing -), pin to its major — v6.1.0 → actions/checkout@v6. If git ls-remote is unavailable, read the resolved tag from https://github.com///releases/latest.

Don't commit yet — the CD workflow (step 8) is committed together with it.

1. CD workflow (release automation) — copy templates/cd.yml (this skill dir)

to .github/workflows/cd.yml. No placeholder to replace. Its versioned actions (actions/checkout, Swatinem/rust-cache) are the same ones resolved in step 7 — reuse those pins; dtolnay/rust-toolchain@stable stays as-is. Commit both workflows together: git add --all && git commit -m "Added GitHub Actions CI/CD workflows".

CI behavior (encoded in the template)

• Triggers: push to master, develop, release/**; and all pull requests.
• Concurrency: in-progress runs for the same ref are cancelled on new pushes

to a pull request (cancel-in-progress only for PR events).

• build-and-test job: every trigger — cargo build --all-targets +

cargo test, across an OS matrix (ubuntu-latest, windows-latest, fail-fast: false, per-OS cache key).

• lint-and-format job: gated by if: github.event_name == 'pull_request',

so cargo fmt --check and cargo clippy -D warnings run only on pull requests.

• docs job: gated by if: github.ref == 'refs/heads/master' and

needs: build-and-test, so it runs only on master after build/test pass. Builds cargo doc and deploys it to GitHub Pages. Requires Pages enabled for the repo (Settings → Pages → Source: GitHub Actions).

• coverage job: gated by if: github.ref == 'refs/heads/develop' and

needs: build-and-test, so it runs only on develop. Generates lcov via cargo llvm-cov and uploads to Codecov. Requires a CODECOV_TOKEN repo secret (Settings → Secrets and variables → Actions).

CD behavior (encoded in the template)

cd.yml is the release-automation workflow. Triggers on push to master that touches Cargo.toml.

• build job: cargo build --all-targets + cargo test gate — never tag a

broken master.

• release job (needs: build, permissions: contents: write): reads the

version from Cargo.toml via cargo get (package.version, falling back to workspace.package.version for a virtual workspace), and if that tag doesn't already exist, creates + pushes v, then merges master into develop (--no-ff). Idempotent — re-running on an unchanged version is a no-op.

Adjust per project

The templates are a strict baseline; toggle these per project:

• docs job (ci.yml) — on by default: builds cargo doc and deploys to

GitHub Pages on master. Remove the entire docs job for a binary-only crate or any repo with no Pages setup. Requires Pages enabled (Settings → Pages → Source: GitHub Actions); without it the job fails.

• submodules — off by default. If the repo has a .gitmodules, add

with: submodules: true under each actions/checkout step that needs the submodule contents (at minimum build-and-test in ci.yml). Use recursive for nested submodules. Private submodules also need a PAT in token: — the default GITHUB_TOKEN cannot clone other private repos.

Verify the workflow with act

Run the CI workflow locally in Docker with act before pushing — when the tooling is present. First check for it:

command -v act && docker info >/dev/null 2>&1

If act is not on PATH or Docker is not running, skip this whole section — it is optional validation, not a failure; state in the final report that act verification was skipped and why. Otherwise, from the project root:

1. act -l — list the jobs act resolves.
2. act push — only build-and-test runs; lint-and-format is skipped by the

PR gate.

1. act pull_request — both jobs run.

The medium image (catthehacker/ubuntu:act-latest) is sufficient; pin it non-interactively with -P ubuntu-latest=catthehacker/ubuntu:act-latest. Confirm step 2 skips lint/format and step 3 includes them. Caveats: act runs Linux containers, so the windows-latest matrix leg can't execute (expect only the ubuntu-latest leg); the docs job (real GitHub Pages) and coverage job (Codecov, develop-only) can't run under act. Scope act to the runnable jobs with act push -j build-and-test and act pull_request -j lint-and-format.

Report the created project path, any steps skipped because the project was already partially set up, and the act results (or that act verification was skipped and why).

Source & license

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

• Author: jambolo
• Source: jambolo/claude-skills
• License: MIT

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