pi-rust-skills 0.1.0

package/references/RUST_COMMANDS.md

@@ -0,0 +1,69 @@
+# Rust Command Reference
+
+## Toolchain
+
+```bash
+rustc --version
+cargo --version
+rustup show active-toolchain
+rustup component add rustfmt clippy
+rustup target list --installed
+```
+
+## Inspect project
+
+```bash
+cargo metadata --no-deps --format-version 1
+cargo tree
+cargo tree -e features
+cargo tree -d
+cargo locate-project
+```
+
+## Build and test
+
+```bash
+cargo check
+cargo check --all-targets --all-features
+cargo build
+cargo build --release
+cargo test
+cargo test --all-features
+cargo test test_name -- --nocapture
+cargo test --doc
+```
+
+## Formatting and linting
+
+```bash
+cargo fmt
+cargo fmt --check
+cargo clippy --all-targets --all-features -- -D warnings
+```
+
+## Documentation
+
+```bash
+cargo doc --no-deps --open
+RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
+```
+
+## Publishing
+
+```bash
+cargo package --list
+cargo package
+cargo publish --dry-run
+cargo publish
+```
+
+## Optional tools
+
+```bash
+cargo install cargo-audit cargo-deny cargo-nextest cargo-bloat cargo-expand
+cargo audit
+cargo deny check
+cargo nextest run
+cargo bloat --release --crates
+cargo expand
+```

package/scripts/list-skills.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+
+const root = path.resolve(new URL("..", import.meta.url).pathname);
+const skillsRoot = path.join(root, "skills");
+
+async function walk(dir) {
+  const entries = await readdir(dir);
+  const skillDirs = [];
+  for (const entry of entries) {
+    const full = path.join(dir, entry);
+    const info = await stat(full);
+    if (!info.isDirectory()) continue;
+    try {
+      await stat(path.join(full, "SKILL.md"));
+      skillDirs.push(full);
+    } catch {
+      skillDirs.push(...(await walk(full)));
+    }
+  }
+  return skillDirs;
+}
+
+function frontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n/);
+  const fields = {};
+  if (!match) return fields;
+  for (const line of match[1].split("\n")) {
+    const idx = line.indexOf(":");
+    if (idx === -1) continue;
+    fields[line.slice(0, idx).trim()] = line.slice(idx + 1).trim().replace(/^['"]|['"]$/g, "");
+  }
+  return fields;
+}
+
+const rows = [];
+for (const dir of await walk(skillsRoot)) {
+  const content = await readFile(path.join(dir, "SKILL.md"), "utf8");
+  const fm = frontmatter(content);
+  rows.push({ name: fm.name, description: fm.description });
+}
+
+for (const row of rows.sort((a, b) => a.name.localeCompare(b.name))) {
+  console.log(`/skill:${row.name}`);
+  console.log(`  ${row.description}`);
+}

package/scripts/validate-skills.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+
+const root = path.resolve(new URL("..", import.meta.url).pathname);
+const skillsRoot = path.join(root, "skills");
+const namePattern = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
+const errors = [];
+const warnings = [];
+
+async function walk(dir) {
+  const entries = await readdir(dir);
+  const skillDirs = [];
+  for (const entry of entries) {
+    const full = path.join(dir, entry);
+    const info = await stat(full);
+    if (info.isDirectory()) {
+      try {
+        await stat(path.join(full, "SKILL.md"));
+        skillDirs.push(full);
+      } catch {
+        const nested = await walk(full);
+        skillDirs.push(...nested);
+      }
+    }
+  }
+  return skillDirs;
+}
+
+function parseFrontmatter(content, file) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n/);
+  if (!match) {
+    errors.push(`${file}: missing YAML frontmatter`);
+    return {};
+  }
+
+  const fields = {};
+  for (const line of match[1].split("\n")) {
+    const idx = line.indexOf(":");
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    let value = line.slice(idx + 1).trim();
+    value = value.replace(/^['"]|['"]$/g, "");
+    fields[key] = value;
+  }
+  return fields;
+}
+
+const skillDirs = await walk(skillsRoot);
+const names = new Map();
+
+for (const dir of skillDirs) {
+  const file = path.join(dir, "SKILL.md");
+  const rel = path.relative(root, file);
+  const content = await readFile(file, "utf8");
+  const fm = parseFrontmatter(content, rel);
+
+  if (!fm.name) errors.push(`${rel}: frontmatter requires name`);
+  if (!fm.description) errors.push(`${rel}: frontmatter requires description`);
+
+  if (fm.name && !namePattern.test(fm.name)) {
+    errors.push(`${rel}: invalid skill name '${fm.name}'`);
+  }
+
+  if (fm.name && fm.name.length > 64) {
+    errors.push(`${rel}: skill name exceeds 64 characters`);
+  }
+
+  if (fm.description && fm.description.length > 1024) {
+    errors.push(`${rel}: description exceeds 1024 characters`);
+  }
+
+  if (fm.name && names.has(fm.name)) {
+    errors.push(`${rel}: duplicate skill name '${fm.name}' also found in ${names.get(fm.name)}`);
+  }
+  if (fm.name) names.set(fm.name, rel);
+
+  if (!content.includes("## Workflow")) {
+    warnings.push(`${rel}: consider adding a '## Workflow' section`);
+  }
+}
+
+if (skillDirs.length === 0) errors.push("no skills found");
+
+if (warnings.length > 0) {
+  console.warn("Warnings:");
+  for (const warning of warnings) console.warn(`- ${warning}`);
+}
+
+if (errors.length > 0) {
+  console.error("Errors:");
+  for (const error of errors) console.error(`- ${error}`);
+  process.exit(1);
+}
+
+console.log(`Validated ${skillDirs.length} skills successfully.`);

package/skills/rust-async-tokio/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: rust-async-tokio
+description: Builds and reviews Rust async code using Tokio, async traits, streams, channels, cancellation, task supervision, graceful shutdown, backpressure, and nonblocking I/O. Use for Rust networking, services, and async runtime work.
+license: MIT
+compatibility: Tokio-based Rust projects or projects considering async Rust.
+---
+
+# Rust Async Tokio
+
+Use this skill when implementing or reviewing async Rust, especially Tokio services, clients, workers, daemons, queues, and network applications.
+
+## Workflow
+
+1. Inspect `Cargo.toml`, workspace shape, feature flags, target crates, and `rust_project_context` output when available.
+2. Confirm whether async is actually needed. Do not add Tokio for simple CPU-bound or synchronous CLI work.
+3. Identify runtime boundaries: binary entry point, library API, spawned tasks, blocking sections, and shutdown path.
+4. Ensure every task has ownership, cancellation, supervision, and error reporting strategy.
+5. Check that `.await` points do not hold mutex guards, borrowed temporaries, or other resources longer than intended.
+6. Add integration tests for cancellation, timeout, graceful shutdown, and error paths.
+
+## Tokio rules
+
+- Use `tokio::spawn` for independent `Send + 'static` work.
+- Use `tokio::task::spawn_blocking` for CPU-heavy or blocking filesystem/process work.
+- Use `tokio::select!` for shutdown and cancellation.
+- Prefer `JoinSet` for supervising groups of tasks.
+- Prefer bounded channels for producer/consumer systems.
+- Avoid `std::sync::Mutex` in async code when lock contention crosses `.await`; use `tokio::sync::Mutex` carefully or restructure ownership.
+
+## Observability
+
+- Use `tracing` spans around request, worker, queue, and task boundaries.
+- Report task failures explicitly; do not detach tasks that can fail silently.
+- Track queue depth, timeouts, retries, and shutdown duration when operating a service.
+- Include enough context in errors to identify the runtime boundary that failed.
+
+## Graceful shutdown pattern
+
+```rust
+let token = CancellationToken::new();
+let worker_token = token.clone();
+
+let worker = tokio::spawn(async move {
+    loop {
+        tokio::select! {
+            _ = worker_token.cancelled() => break,
+            result = do_one_unit_of_work() => {
+                result?;
+            }
+        }
+    }
+    Ok::<_, anyhow::Error>(())
+});
+
+tokio::signal::ctrl_c().await?;
+token.cancel();
+worker.await??;
+```
+
+Use `tokio-util` only if the project already accepts that dependency or cancellation tokens are worth it.
+
+## Async traits
+
+- Native `async fn` in traits is fine when object safety is not required.
+- Use boxed futures or `async-trait` only when dynamic dispatch is required and the tradeoff is acceptable.
+- Document `Send` requirements when futures cross thread boundaries.
+
+## Testing
+
+```bash
+cargo test --workspace --all-features
+cargo test -p crate_name async_test_name -- --nocapture
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+```
+
+Use timeouts in tests to avoid hangs:
+
+```rust
+tokio::time::timeout(Duration::from_secs(1), operation()).await??;
+```
+
+Use `tokio::time::pause` and `advance` for timer-heavy code. Prefer channels, cancellation tokens, and controlled clocks over sleeps.
+
+## Output expectations
+
+Explain task ownership, cancellation behavior, backpressure, and validation commands. Flag any blocking or lock-across-await risks explicitly.
+
+## Avoid
+
+- Do not spawn untracked background tasks.
+- Do not run blocking I/O or CPU-heavy work on executor worker threads.
+- Do not use unbounded channels or unlimited task spawning when producers can outrun consumers.

package/skills/rust-build-cross/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: rust-build-cross
+description: Configures and reviews Rust build scripts, native dependencies, cc/pkg-config/cmake integration, target triples, linker settings, cross-compilation, platform-specific cfgs, and release packaging. Use for Rust builds that depend on native tooling or multiple platforms.
+license: MIT
+compatibility: Rust stable. Cross builds may require target toolchains, linkers, native SDKs, pkg-config, cc, cmake, bindgen, or cross.
+---
+
+# Rust Build Cross
+
+Use this skill when Rust builds involve `build.rs`, native libraries, generated bindings, cross-compilation, custom linkers, or platform packaging.
+
+## Workflow
+
+1. Inspect `Cargo.toml`, workspace shape, feature flags, target crates, `.cargo/config.toml`, build scripts, and `rust_project_context` output when available.
+2. Identify target triples, host tools, native dependencies, generated files, and linker requirements.
+3. Make build scripts deterministic and explicit about rerun conditions.
+4. Validate native and cross targets separately.
+5. Document setup requirements for contributors and CI.
+
+## Build script rules
+
+- Emit `cargo:rerun-if-changed` and `cargo:rerun-if-env-changed` precisely.
+- Prefer `pkg-config`, `cc`, `cmake`, or `bindgen` according to the dependency's build model.
+- Keep generated files in `OUT_DIR` unless the project intentionally checks them in.
+- Avoid network access and non-deterministic downloads in `build.rs`.
+- Preserve useful error messages for missing SDKs, linkers, headers, or libraries.
+
+## Cross-compilation
+
+- Confirm host triple, target triple, linker, C compiler, and required system libraries.
+- Use target-specific dependencies and `cfg` gates for platform code.
+- Add `.cargo/config.toml` only when the project needs stable target configuration.
+- Validate at least one native build before diagnosing cross-only failures.
+
+## Commands
+
+```bash
+cargo check --workspace --all-targets --all-features
+cargo build --target target-triple
+cargo test --workspace --all-features
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+```
+
+Use `cross build`, `zig cc`, or platform SDK commands only when the project already uses them or the target requires them.
+
+## Avoid
+
+- Do not hide native dependency failures by disabling features silently.
+- Do not write generated files into source directories unless release policy requires it.
+- Do not assume Linux linker settings work on macOS or Windows.
+
+## Output expectations
+
+Report host and target assumptions, native dependency requirements, build script changes, validation commands, and packaging implications.

package/skills/rust-cli/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: rust-cli
+description: Builds Rust command-line applications with clap, config files, environment variables, structured errors, logging, shell completions, tests, packaging, and cross-platform behavior. Use when creating or improving Rust CLI tools.
+license: MIT
+compatibility: Rust stable toolchain. clap, tracing, serde, and assert_cmd are optional project dependencies.
+---
+
+# Rust CLI
+
+Use this skill for Rust command-line tools, developer utilities, admin tools, and terminal workflows.
+
+## Workflow
+
+1. Inspect `Cargo.toml`, workspace shape, feature flags, target crates, and `rust_project_context` output when available.
+2. Define the CLI contract first: commands, flags, input/output, exit codes, and config precedence.
+3. Keep `main.rs` thin. Put real logic in library modules that tests can call directly.
+4. Use structured errors internally and user-friendly messages at the CLI boundary.
+5. Add integration tests that execute the binary for critical commands.
+6. Validate behavior on paths with spaces and platform-specific path separators.
+
+## Recommended layout
+
+```text
+src/
+├── main.rs
+├── cli.rs
+├── config.rs
+├── error.rs
+└── commands/
+    ├── mod.rs
+    └── scan.rs
+tests/
+└── cli.rs
+```
+
+## clap pattern
+
+```rust
+use clap::{Parser, Subcommand};
+
+#[derive(Debug, Parser)]
+#[command(name = "tool-name", version, about)]
+pub struct Cli {
+    #[arg(short, long, global = true)]
+    pub verbose: bool,
+
+    #[command(subcommand)]
+    pub command: Command,
+}
+
+#[derive(Debug, Subcommand)]
+pub enum Command {
+    Scan { path: std::path::PathBuf },
+}
+```
+
+## Error handling
+
+- `main` should convert errors into stable exit codes and messages.
+- Use `eprintln!` only at the boundary.
+- Use `tracing` or `log` for diagnostics, not normal output.
+- Keep stdout machine-readable when the command is designed for scripting.
+
+## CLI contract
+
+- Document config precedence, usually flags, environment, config file, then defaults.
+- Reserve stdout for primary output and stderr for diagnostics, progress, and errors.
+- Define stable exit codes for success, usage/config errors, input errors, and internal failures.
+- Respect TTY behavior: color, progress bars, prompts, and paging should be disabled or configurable in non-interactive mode.
+- Generate shell completions and manpages when the tool is meant for broad distribution.
+
+## Testing commands
+
+Useful dev dependencies:
+
+```toml
+[dev-dependencies]
+assert_cmd = "2"
+predicates = "3"
+tempfile = "3"
+```
+
+Example:
+
+```rust
+#[test]
+fn prints_help() {
+    let mut cmd = assert_cmd::Command::cargo_bin("tool-name").unwrap();
+    cmd.arg("--help").assert().success();
+}
+```
+
+Add golden output tests for stable help, JSON, or text output. Keep golden files small and review intentional changes.
+
+## Validation
+
+```bash
+cargo fmt
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+cargo test --workspace --all-features
+cargo test -p crate_name --test cli
+cargo run -- --help
+```
+
+## Output expectations
+
+Document the CLI contract, files changed, example invocations, and any future packaging steps such as shell completions, manpages, Homebrew, Scoop, or cargo-binstall.
+
+## Avoid
+
+- Do not mix diagnostics into machine-readable stdout.
+- Do not make config precedence implicit.
+- Do not add hidden panics for invalid user input.

package/skills/rust-code-review/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: rust-code-review
+description: Reviews Rust code for correctness, ownership and lifetime issues, error handling, API design, unsafe usage, concurrency risks, performance traps, cargo features, tests, and idiomatic style. Use when asked to audit or improve Rust code.
+license: MIT
+compatibility: Works best in a Cargo project with rustfmt, clippy, and tests available.
+---
+
+# Rust Code Review
+
+Use this skill for Rust pull request review, local code audit, bug-risk review, and idiomatic refactoring suggestions.
+
+## Workflow
+
+1. Gather context. Read `Cargo.toml`, workspace shape, feature flags, target crates, changed files, public APIs, tests, and any failure logs. Use `rust_project_context` when available.
+2. Run or request validation commands where practical:
+   ```bash
+   cargo fmt --check
+   cargo check --workspace --all-targets --all-features
+   cargo clippy --all-targets --all-features -- -D warnings
+   cargo test --all-features
+   ```
+3. Review in this priority order:
+   - Soundness and safety.
+   - Correctness and edge cases.
+   - Error handling and observability.
+   - API design and maintainability.
+   - Performance and allocation behavior.
+   - Tests and documentation.
+4. Prefer actionable patches over broad commentary.
+5. Do not suggest adding dependencies unless they simplify real complexity or reduce risk.
+
+## Severity guide
+
+- High: soundness, security, data loss, panics on normal input, or broken public contracts.
+- Medium: incorrect edge cases, cancellation/resource leaks, portability bugs, or missing tests for risky behavior.
+- Low: maintainability, clarity, docs, or style issues that do not change behavior.
+
+## Rust-specific checklist
+
+### Ownership and lifetimes
+
+- Avoid unnecessary cloning. Prefer borrowing when lifetimes stay simple.
+- Do not overuse explicit lifetimes; let elision work unless public API clarity improves.
+- Watch for returning references tied to temporary values.
+- Prefer owned return types when borrowing would make the API brittle.
+
+### Errors
+
+- Library code should usually return typed errors or `thiserror`-style enums.
+- Application boundaries can use `anyhow`-style context.
+- Preserve source errors and add context at I/O, network, parsing, and external process boundaries.
+- Avoid `unwrap`, `expect`, and `panic` outside tests, examples, initialization invariants, or clearly documented impossible states.
+
+### Unsafe code
+
+- Flag every `unsafe` block for justification.
+- Require a nearby safety comment explaining invariants.
+- Check aliasing, initialization, lifetime extension, FFI contracts, and thread-safety assumptions.
+- Prefer safe abstractions around unsafe internals.
+
+### Async and concurrency
+
+- Avoid holding locks across `.await`.
+- Check that blocking work is not run on async executor workers.
+- Prefer bounded channels when backpressure matters.
+- Confirm cancellation behavior and task shutdown.
+
+### API design
+
+- Public APIs should use clear types, minimal generics, and docs with examples.
+- Prefer `AsRef<Path>` for path-like inputs and `impl Into<String>` sparingly.
+- Avoid exposing concrete dependency types unless they are part of the intended contract.
+- Check MSRV, edition, feature flags, and semver compatibility before recommending public API changes.
+- Treat public type names, trait bounds, error variants, feature defaults, and re-exports as compatibility surface.
+
+### Feature and workspace coverage
+
+- Review feature-gated code with `--all-features` and the default feature set when both matter.
+- For workspaces, identify the affected package and run `cargo check -p crate_name --all-targets --all-features` when the full suite is too broad.
+- Check generated code, proc macro expansion, and build scripts when the diff touches them.
+
+## Review output format
+
+Lead with findings. Use this structure:
+
+```markdown
+## Summary
+
+## High-risk findings
+
+## Correctness issues
+
+## Maintainability improvements
+
+## Suggested patch
+
+## Validation
+```
+
+For each finding include: file, line or symbol, problem, why it matters, and a concrete fix.
+
+## Avoid
+
+- Do not bury high-risk findings below summaries.
+- Do not recommend broad rewrites when a local fix resolves the issue.
+- Do not weaken lints or tests without a clear compatibility reason.

package/skills/rust-crate-publishing/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: rust-crate-publishing
+description: Prepares Rust crates for publication to crates.io, including Cargo.toml metadata, README, license, docs, examples, semver, feature flags, cargo package checks, release tags, and post-publish validation. Use before publishing Rust crates.
+license: MIT
+compatibility: Rust stable with cargo. crates.io publishing requires a configured registry token.
+---
+
+# Rust Crate Publishing
+
+Use this skill when preparing a Rust crate or workspace member for crates.io or an internal Cargo registry.
+
+## Workflow
+
+1. Inspect `Cargo.toml`, workspace shape, feature flags, target crates, and `rust_project_context` output when available.
+2. Inspect README, license, public API, examples, tests, and release history.
+3. Confirm crate name availability outside the code task; do not assume an unpublished name is available.
+4. Ensure metadata is complete:
+   - `description`
+   - `license` or `license-file`
+   - `repository`
+   - `homepage` if useful
+   - `documentation` if custom
+   - `readme`
+   - `keywords` and `categories`
+   - `rust-version`
+5. Confirm public API docs build without warnings.
+6. Run package dry-run before publishing.
+
+## Commands
+
+```bash
+cargo fmt --check
+cargo clippy --all-targets --all-features -- -D warnings
+cargo test --all-features
+RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
+cargo semver-checks
+cargo package --allow-dirty --list
+cargo package
+cargo publish --dry-run
+```
+
+Use `--allow-dirty` only for inspection. Do not publish dirty working trees.
+Use `cargo semver-checks` when installed or when a public crate is being released from an existing version.
+
+## Cargo.toml metadata template
+
+```toml
+[package]
+name = "crate-name"
+version = "0.1.0"
+edition = "2024"
+rust-version = "1.85"
+description = "One-sentence description under 200 characters."
+license = "MIT OR Apache-2.0"
+repository = "https://github.com/user/repo"
+readme = "README.md"
+keywords = ["rust", "cli"]
+categories = ["command-line-utilities"]
+exclude = [".github/", "target/"]
+```
+
+## Semver rules
+
+- `0.x` can still break users; document breaking changes.
+- Public type names, trait bounds, features, and error variants are API.
+- Removing a feature flag or changing default features can be breaking.
+- Prefer additive changes for patch/minor releases.
+- Check MSRV changes, default feature changes, and re-export changes as compatibility events.
+
+## Workspace publishing
+
+- Publish dependency crates before crates that depend on them.
+- Confirm every workspace member has correct `version`, `license`, `repository`, and `readme` metadata.
+- Use `cargo publish -p crate_name --dry-run` for each publishable member.
+- Do not publish private helper crates accidentally; set `publish = false` where needed.
+
+## Release safety
+
+- Verify crates.io owners and registry token setup outside the repository.
+- Never print or store registry tokens in logs, docs, or scripts.
+- Create a release tag only after the publish command succeeds.
+- After publishing, install or depend on the published version in a clean temporary project for a smoke check.
+
+## README checklist
+
+- What the crate does.
+- Install command.
+- Minimal example.
+- Feature flags.
+- MSRV if set.
+- License.
+
+## Output expectations
+
+Report readiness, missing metadata, dry-run results, and exact publish command. Never claim a publish succeeded unless the publish command was actually run and returned success.
+
+## Avoid
+
+- Do not publish from a dirty working tree.
+- Do not assume workspace version bumps are harmless.
+- Do not remove old feature flags or defaults without documenting the breaking change.